Difficulties documenting enum classes?

Question

I'm trying to document a module I'm maintaining, and I'm finding it very difficult to get my enum classes documented properly. For instance, here's one that I'd like to document properly (source):

class QOSLevel(Enum):
    '''Quality of service levels'''

    #: 500ms (fastest available)
    EXPRESS = '0'                  

    #: 750ms                       
    REAL_TIME = '1'                

    #: 1000ms                      
    FAST = '2'                     

    #: 1500ms                      
    MODERATE = '3'                 

    #: 3000ms                      
    SLOW = '4'                     

    #: 5000ms                      
    DELAYED = '5'                  

My documentation for this is here (source):

.. autoclass:: tda.streaming.StreamClient.QOSLevel 
  :members:                                        
  :undoc-members:                                  
  :member-order: bysource                          

The output looks like this:

Two things are immediately wrong here:

• First off, the documentation strings I set are not rendering. I've attempted to follow some advice I've received before that worked for generic attributes, but it seems enums are somehow handled differently?

• Secondly, it seems the :member-order: bysource directive is being ignored. I tried setting this both here and in conf.py, and neither place seems to allow the fields to be emitted in the proper order.

I'm using sphinx v3.0.4 for what it's worth. You can try to replicate the error by copy-pasting the following into your terminal:

git clone https://github.com/alexgolec/tda-api.git
cd tda-api
git checkout remotes/origin/autodoc-bysource-not-working
virtualenv -v virtualenv
source virtualenv/bin/activate
pip install -r requirements.txt
make -f Makefile.sphinx html
open docs-build/html/streaming.html  # Only works on Mac OS    

Answer 1

The problem is that the QOSLevel class is nested inside the StreamClient class. The following works (note the colons):

.. autoclass:: tda.streaming::StreamClient.QOSLevel

See How to document nested classes with Sphinx's autodoc?.