Трудности с документированием классов enum?

Я пытаюсь задокументировать поддерживаемый мной модуль, и мне очень трудно правильно задокументировать мои классы перечисления. Например, вот тот, который я хотел бы правильно задокументировать (источник):

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'                  

Моя документация по этому поводу находится здесь (исходный код):

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

Результат выглядит так:

введите описание изображения здесь

Здесь сразу две ошибки:

  • Во-первых, установленные мной строки документации не отображаются. Я попытался последовать совету Я получал раньше, что работал с универсальными атрибутами, но кажется, что перечисления как-то обрабатываются по-другому?

  • Во-вторых, похоже, что директива :member-order: bysource игнорируется. Я попытался установить это как здесь, так и в conf.py, и, похоже, ни одно место не позволяет генерировать поля в правильном порядке.

Пользуюсь sphinx v3.0.4 по назначению. Вы можете попытаться воспроизвести ошибку, скопировав в свой терминал следующее:

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    

person Alex    schedule 28.05.2020    source источник
comment
Проблема в том, что класс QOSLevel вложен в класс StreamClient. Это работает: .. autoclass:: tda.streaming::StreamClient.QOSLevel (обратите внимание на двоеточия). См. stackoverflow.com/q/27337534/407651.   -  person mzjn    schedule 28.05.2020
comment
Это оно! Не стесняйтесь превратить этот комментарий в ответ, и я его приму.   -  person Alex    schedule 29.05.2020


Ответы (1)


Проблема в том, что класс QOSLevel вложен в класс StreamClient. Следующие работы (обратите внимание на двоеточия):

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

См. Как документировать вложенные классы с помощью autodoc Sphinx?.

person mzjn    schedule 29.05.2020