How to document linkable constants with sphinx

Question

How can I properly document a constant, say foo = 4 in Python(3) Code with Sphinx in such a way, that I can access them with something like :attr:`foo`?

My current solution would be creating a class and moving the constants into properties:

class Constants:
    @property
    def foo(self):
        """Cool Documentation."""
        return 4

Then add in the classes.rst file:

..autoclass:: Constants
   :members:

However this should not be the right way to do it, as it forces me to carry around an instance of Constants in my Code.

In case it matters: I'm using Numpy style

I already read that one, however I can't really find a solution in there. It seems like the directives `automodule` or `autodata` could be helpful. However I can't make it work. — Smudoxo, Jun 13 '18 at 10:23
There are five answers to that question. Please show us exactly what you tried (preferrably in the form of a [mcve]). — mzjn, Jun 13 '18 at 10:36
Thank you for your push! I played a bit around with the answers in the post. My mistake so far was caused by my lack of understanding how to work with the sphinx directives. (Unfortunately this is still the case). I used .. autoclass:: . :members: combined with the enum.Enum class and #: Comments which didn't give me the documentation style that I wanted. However In my answer below I stated my current solution. I would be happy to get your feedback on that one. — Smudoxo, Jun 14 '18 at 14:09

score 1 · Accepted Answer · answered Jun 14 '18 at 14:03

I found a reasonable solution for my problem. I added a file constants.py

    #: :obj:`int` : 
    #: Cool documentation about foo
    foo = 4

and to the classes.rst I added the lines

    .. automodule:: MODULE_WHERE_THE_FILE_IS_IN.constants
        :members:

This creates a documentation of the foo constant and I can create link to foo with:

    :const:`MODULE_WHERE_THE_FILE_IS_IN.constants.foo`

or

    :const:`~MODULE_WHERE_THE_FILE_IS_IN.constants.foo`

How to document linkable constants with sphinx

1 Answers1