Convert docstrings of modules in libtaskotron/directives/
directory into sphinx format.
Details
- Reviewers
kparal tflink - Maniphest Tasks
- T164: convert docstrings to sphinx format
- Commits
- rLTRN8c82af1eea32: convert docstrings of directives to sphinx format
generate sphinx documentation for every module in
directives directory with ":members:", ":undoc-members:" and
":private-members:"
Diff Detail
- Repository
- rLTRN libtaskotron
- Lint
Lint Skipped - Unit
Unit Tests Skipped
libtaskotron/directives/bodhi_comment_directive.py | ||
---|---|---|
142–143 | This must be :param parsed_comments: already existing AutoQA comments for the update :type parsed_comments: list of dict | |
295–306 | You can use a proper reST "bold" here. | |
299 | ``noarch`` looks better | |
303–305 | It's nice to use ``True`` and similarly for False. It's not required, but it looks better (denotes the values) in the generated docs. Similarly for the 0 above. And similarly in other docstrings. | |
369–373 | This gets distorted, you need to make it a preformatted block. | |
374 | ``checkname`` in ``env_data`` |
@tflink: another thing is, from what I understand, classes without "main" docstring (that docstring right after class XY:) won't appear in result at all, even when they have docstrings in some of their methods. And methods/classes with underscore at the beginning of their name won't appear there either. To include both, one must add :undoc-members: and
:private-members: besides :members:. Are we planning to ad these into library.rst too?
Are the directives expected to be added into library.rst?
I hadn't been planning on it, no. The plan had been to use the directive documentation stuff that @roshi is working on in D93 instead. Do you think that it would be better to add them to library.rst?
another thing is, from what I understand, classes without "main" docstring (that docstring right after class XY:) won't appear in result at all, even when they have docstrings in some of their methods. And methods/classes with underscore at the beginning of their name won't appear there either. To include both, one must add :undoc-members: and :private-members: besides :members:.
I thought that just using :members: would pull in everything that had a docstring, regardless of whether the class itself had a docstring but I could be wrong on that one.
I guess this should read Taskotron :-)