python 'constants'

6 views
Skip to first unread message

Louis King

unread,
Aug 20, 2022, 4:57:59 PMAug 20
to sphinx...@googlegroups.com
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

unread,
Aug 26, 2022, 5:49:05 PMAug 26
to sphinx...@googlegroups.com
When I look at the autodoc documentation
I think my docstrings  & #: in function _main looks like the example.
Reply all
Reply to author
Forward
0 new messages