Трудности с документированием классов enum? - PullRequest
Новая
       146

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

1 голос
/ 28 мая 2020

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

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

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

enter image description here

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

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

  • Во-вторых, похоже, что директива :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

1 Ответ

2 голосов
/ 29 мая 2020

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

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

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

...