python 'constants'

[Louis King]

Hi all,

I am trying to document python "constants" at the class level and at the level of a method within the class. I am using the tag "#:" following the docstring for the call and the method.

My sphinx conf.py file contains:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
]

Things seem to work following the class but not within the method. My questions are:

1. Why does the (document testing) constant 'bell' show up out of any order following the entry for _main() but before stop()?
2. Why doesn't the useful constant "_yellow" declared within the method _main() not show up at all?
   

Fragments of my code and the output follow? (Yes I think I fat finger posted twice. sorry)

<code>

class Run:
    """
    This class runs as a thread in the background as long as TrainThing is running.

.

.

.

    :raises ValueError: If constant ON_threshold <= OFF_threshold.

    **Constants:**
    """
    #: (dict) The mix of red, green, blue LED for 'yellow' LED
    #: * * who knows why?
    bell = {'r': int(255 * 0.9375), 'g': int(255 * 0.75), 'b': 0}
    #: (float) Time between display updates
    UPDATE_TIME = 2.0
    #: (int) The degrees C when the fan is turned on in the auto mode.
    #: RPi hard threshold of 85 C, soft 80 C
    ON_threshold = 65
    #: (int) The degrees C when the fan is turned off in the auto mode.
    #: OFF_threshold must be less than ON_threshold
    OFF_threshold = 55

.

.

.

    def _main(self) -> None:
        """
        This method sets up the initial display values and then
        every 2 seconds checks status and updating the display for:

        * The fan is on or off.
        * The fan is running in the manually or auto mode.
        * The cpu frequency is Max, Min or in between.
        * the cpu temperature 5 step display ladder.
       
        until variable run_forever is set False by function **stop()**

        **Constant:**
        """
        #: (dict) The mix of red, green, blue LED for 'yellow' LED
        #: continuation line to match above.
        _yellow: Dict[str, int] = {'r': int(255 * 0.9375), 'g': int(255 * 0.75), 'b': 0}

        #: TODO figure out why yellow does not show as a Constant in sphinx

</code>

<output>

 class fan.Run(unicorn)
    This class runs as a thread in the background as long as TrainThing is running.

.

.

.

    Raises:  ValueError – If constant ON_threshold <= OFF_threshold.

    Constants:

OFF_threshold = 55
    (int) The degrees C when the fan is turned off in the auto mode. OFF_threshold must be less than ON_threshold

     (int) The degrees C when the fan is turned on in the auto mode. RPi hard threshold of 85 C, soft 80 C
ON_threshold = 65
    (int) The degrees C when the fan is turned on in the auto mode. RPi hard threshold of 85 C, soft 80 C

UPDATE_TIME = 2.0
    (float) Time between display updates

.

.

.

_main() → None

    This method sets up the initial display values and then every 2 seconds checks status and updating the display for:

        The fan is on or off.

        The fan is running in the manually or auto mode.

        The cpu frequency is Max, Min or in between.

        the cpu temperature 5 step display ladder.

    until variable run_forever is set False by function stop()

    Constant:

bell = {'b': 0, 'g': 191, 'r': 239}
    (dict) The mix of red, green, blue LED for ‘yellow’ LED * * who knows why?

stop() → None¶

</output>

--

Lou
Say what you will about Sisyphus. He always has work.

[Louis King]

When I look at the autodoc documentation

 https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc

I think my docstrings  & #: in function _main looks like the example.