Python "Constants"

9 views
Skip to first unread message

Louis King

unread,
Aug 20, 2022, 4:31:59 PMAug 20
to sphinx...@googlegroups.com
Hi All,
I'm sure I'm missing something very basic, I just can't see it. I am trying to document 'constants' used at the Class level and one local to a procedure within the Class. I am using the "#:" tag following the docstrings for the class and the procedure to document the constants.
My sphinx conf.py file includes
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
]
Following the class things work, but not for the procedure within the class.
My questions are:
  1. Why does the (test) constant 'bell' defined after the class docstring appear at the end - out of any order -?
  2. Why doesn't the real constant '_yellow' defined after procedure _main docstring not appear at all?
Code snippets and sphinx out.

<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

    __init__(unicorn) → None

        Initialization starts the FanLib passing the named parameters on_threshold, off_threshold and auto_time so both modules, fan and FanLib, have the same values so the unicorn display set by this module and the auto mode run by FanLib are synchronized. Makes unicorn display methods available and starts the _main method as a thread.

    _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?


 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
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.
Reply all
Reply to author
Forward
0 new messages