Is it necessary to write a docstring for private properties? https://peps.python.org/pep-0008/ says that "Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the def line." Does this also include private properties?
Generally in Python, you should strive for your documentation to be cohesive. Match the style with the rest of your project. You could opt to not document the property at all, use comments only, or write documentation like you did elsewhere.
I personally would suggest the last one and remembering to maintain cohesion.
Related
I am using sphinx-autodoc for documenting a class. I want the methods of the class to correspond to individual entries in the Sphinx TOC, so that they each spawn a link in the 'local TOC' sidebar.
How can I achieve this?
AFAICT, the autoclass directive does not support this. I tried to use autosummary, but I can't get that one to work either: it wants the individual methods in separate .rst files. I would rather have them all on the same page.
I guess I could manually create a section for each member like so:
Foo.bar()
---------
.. automethod:: Foo.bar
But that feels weird and unnecessarily complicated.
I wrote a sphinx plugin called autoclasstoc that does something similar to what you want. The plugin provides a directive that creates a table of links to the documentation for each method of a particular class. The links don't end up in the TOC sidebar, but they still make the class documentation much easier to navigate. It's also worth mentioning that these links can be organized into groups (e.g. public methods, private methods, etc.) and that links to inherited methods are grouped by superclass and collapsed by default.
Even though this doesn't exactly answer your question, it's a good way to achive a similar effect.
I'm trying to remove all the class variables from my Sphinx documentation (because I haven't documented them and it doesn't look good if there's only a list of them) for all the classes of my project including the modules in the folders.
Is there an easy way to do it without having to exclude each one of them?
P.S.: I'm a beginner at this, so the answer could be something easy. Also, this could already be answered, but I couldn't find anything.
You can use :no-undoc-members: to tell sphinx to ignore the undocumented (in your case the class) variables.
:undoc-members: (no value)
If set, autodoc will also generate document for the members not having docstrings:
Here is the documentation - https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-option-automodule-undoc-members
I am using the Sphinx autodoc feature to generate documentation based on the docstrings of my Python library.
The syntax for cross referencing is found here
A label must precede the section in order to allow that section to be referenced from other areas of the documentation.
What I have is a .rst (ReStructeredText) file for one of my classes. It uses
.. autoclass:: classname
:members:
To generate documentation for the class.
My question is, how would I reference the auto-generated methods of the class from another .rst document in the documentation? If I try to place a label within the method's docstring, Sphinx complains. If I try to place a label before the method heading, Sphinx doesn't recognize it.
Is there a simple way to do this, or will I have to explicitly write in my class file the method name and precede that with a label?
Here is an example a reference within the [Python documentation2 doing what I need (I am assuming it used the autodoc feature, though I don't know for sure)
You don't need to add labels. In order to refer to a Python class, method, or other documented object, use the markup provided by the Python domain.
For example, the following defines a cross-reference to the mymethod method:
:py:meth:`mymodule.MyClass.mymethod`
Or even simpler (since the Python domain is the default):
:meth:`mymodule.MyClass.mymethod`
The documentation of TextWrapper.wrap that you link to in the question includes two cross-references of this kind (click on "Show Source" to see the reST markup).
In addition to the excellent answer already provided:
To add an alias to the referenced module (method, function, attribute, etc.), the following syntax is used:
:mod:`Alias Name <package.module>`
This will appear as a reference to Alias Name in the docs, and link to the module provided.
I'm considering Sphinx for documenting Python projects. I'd like the api docs for a class to contain docs for all of the methods that can be called from the class. The default behavior seems to be to provide a links to superclasses. Thus to see all callable methods I have to click back through the inheritance tree. Docs I've seen produced by (I think) javadoc or doxygen show at least the names of all methods that can be called.
Is it possible in sphinx to display docs for local methods, and at least the names of methods defined in superclasses? To me this is desirable. Is there some reason that what I want is not such a good idea? Is there some alternative approach from within Sphinx?
Plan B will be to explore Pydoctor. Any suggestions for a Plan C, D, ... ?
I am using the Sphinx autodoc feature to generate documentation based on the docstrings of my Python library.
The syntax for cross referencing is found here
A label must precede the section in order to allow that section to be referenced from other areas of the documentation.
What I have is a .rst (ReStructeredText) file for one of my classes. It uses
.. autoclass:: classname
:members:
To generate documentation for the class.
My question is, how would I reference the auto-generated methods of the class from another .rst document in the documentation? If I try to place a label within the method's docstring, Sphinx complains. If I try to place a label before the method heading, Sphinx doesn't recognize it.
Is there a simple way to do this, or will I have to explicitly write in my class file the method name and precede that with a label?
Here is an example a reference within the [Python documentation2 doing what I need (I am assuming it used the autodoc feature, though I don't know for sure)
You don't need to add labels. In order to refer to a Python class, method, or other documented object, use the markup provided by the Python domain.
For example, the following defines a cross-reference to the mymethod method:
:py:meth:`mymodule.MyClass.mymethod`
Or even simpler (since the Python domain is the default):
:meth:`mymodule.MyClass.mymethod`
The documentation of TextWrapper.wrap that you link to in the question includes two cross-references of this kind (click on "Show Source" to see the reST markup).
In addition to the excellent answer already provided:
To add an alias to the referenced module (method, function, attribute, etc.), the following syntax is used:
:mod:`Alias Name <package.module>`
This will appear as a reference to Alias Name in the docs, and link to the module provided.