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
<https://github.com/alexgolec/tda-api/blob/autodoc-bysource-not-working/tda/streaming.py#L328>):
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
<https://github.com/alexgolec/tda-api/blob/autodoc-bysource-not-working/docs/streaming.rst>):
.. autoclass:: tda.streaming.StreamClient.QOSLevel
:members:
:undoc-members:
:member-order: bysource
The output looks like this:
[image: Screen Shot 2020-05-28 at 9.58.21 AM.png]
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
<https://stackoverflow.com/questions/61314181/when-using-sphinx-how-can-i-document-members-that-dont-have-docstrings>
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
What gives?
--
You received this message because you are subscribed to the Google Groups
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/sphinx-users/eb70dee9-5897-4b7e-bbb5-51770e2f6697%40googlegroups.com.
