Search code examples
python-sphinx

Show function names with dashes in sidebar with Sphinx and function directive

I'm using Sphinx 7.2.5 with the Furo theme and documenting functions that are not Python and therefore can have dashes in their names. The function directive generally works as desired except that functions with dashes in their names don't show up in the sidebar. I'd appreciate help either fixing this or approaching how to troubleshoot it! Maybe there's an escape character that can be used? Or maybe it's a bug somewhere, but I don't know enough about Sphinx to know where to look.

Here's an example:

.. function:: count-non-empty(nodeset)

  Returns the number of non-empty members of ``nodeset``.

You can see it rendered below https://docs.getodk.org/form-operators-functions/#count, note that count-non-empty is not in the right sidebar.

Code at https://github.com/getodk/docs/blob/master/docs/form-operators-functions.rst?plain=1#L353

Solution

  • We discovered via the Furo theme's discussion board that this is because of Sphinx using the Python domain by default. Python does not allow - in identifiers, but adding primary_domain = 'js' to the Sphinx conf.py should allow these to work correctly.