I'm using sphinx with the numpydoc extension and autosummary. After some experimentation, I added the following options to my conf.py file.
autosummary_generate = True
numpydoc_show_class_members = False
This is giving me a new file for each class referenced like below, and it also creates a summary table of all of the attributes and methods.
.. autosummary::
:toctree: generated/
:nosignatures:
MyClass
The problem is that while there is a summary table of the methods with the first line of the doc string, the names of the methods don't link to anything. How do I get the doc strings of the methods to also create files of their own (or at least generate the documentation in the same file as the class)?
First, make sure that in your conf.py file, the strings 'sphinx.ext.autodoc' and 'sphinx.ext.autosummary' are in the extensions list.
Second, you can either manually make the file with name mymodule.MyClass.rst inside the generate/ directory, which can be something like this:
mymodule.MyClass
================
.. currentmodule:: mymodule
.. autoclass:: MyClass
or, if you have a lot of classes, you can automate it using sphinx-autogen. You can run it from terminal (with cd same as the conf.py file) as :
sphinx-autogen *.rst
It appears that a template is needed to have sphinx generate rst files for the methods. Under _templates/autosummary I added a file named class.rst which looks like this and everything works.
Related
I have a module mod with some submodule submod and use .. automodule:: mod.submod to generate documentation for it.
The signatures of the elements (functions, classes etc.) in the modules now show the qualified name, like mod.submod.my_function(*args, **kwargs).
I would instead like Sphinx to just show the name of the function, i.e. the signature my_function(*args, **kwargs).
Do I have any way to drop the leading module and submodules in the signature?
Omitting module and package names preceding functions, methods and variables is done by setting the add_module_name configuration in your conf.py:
add_module_names = False
This is not obvious because of the numerous autodoc configurations that together with the sphinx-napoleon configurations make you expect the configuration elsewhere.
Yes, try this in docs/mod/submod.rst:
.. automodule:: mod.submod
.. autofunction:: my_function
See example HTML build and reST source in Pyramid documentation.
Bonus: see the Sphinx docs for Cross-referencing syntax:
If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:~Queue.Queue.get will refer to Queue.Queue.get but only display get as the link text.
I'm having trouble controlling Sphinx's autodoc feature.
My directory structure is:
projname
+ projname
__init__.py
Scheduler.py containing class Scheduler
+ docs
conf.py
index.rst
conf.py contains:
sys.path.insert(0, os.path.abspath('../projname'))
And index.rst contains:
.. automodule:: Scheduler
This does what I want, except that the generated Scheduler class documentation comes out as:
class Scheduler.Scheduler()
...[all the methods etc documented correctly]ΒΆ
I could live with that, but in order to cross reference the class elsewhere, I have to refer to is as
:class:`Scheduler.Scheduler`
which leads to horribly ungainly documentation.
How do I persuade autodoc to omit the module name from the class documentation - I think it must be possible as other package documentation does seem to have it?
Charles
I think the ..currentmodule directive will help you here.
The package I am documenting consists of a set of *.py files, most containing one class with a couple of files being genuine modules with functions defined. I do not need to expose the fact that each class is in a module so I have added suitable from statements in the __init__.py file e.g.
from base import Base
so that the user can use the import pkg command and does not then have to specify the module that contains the class:
import pkg
class MyBase(pkg.Base): # instead of pkg.base.Base ...
...
The problem is that Sphinx insists on documenting the class as pkg.base.Base. I have tried to set the add_module_names = False in conf.py. However this results in Sphinx showing the class as simply Base instead of pkg.Base. Additionally this also ruins the documentation of the couple of *.py files that are modules.
How do I make Sphinx show a class as pkg.Base?
And how do I set the add_module_names directive selectively for each *.py file?
Here is a way to accomplish what the OP asks for:
Add an __all__ list in pkg/__init__.py:
from base import Base # Or use 'from base import *'
__all__ = ["Base"]
Use .. automodule:: pkg in the .rst file.
Sphinx will now output documentation where the class name is shown as pkg.Base instead of pkg.base.Base.
I've incorporated the answers I found in a scalable-ish form factor:
my_project/
__init__.py
mess.py
mess.py:
class MyClass:
pass
class MyOtherClass(MyClass):
pass
__init__.py:
from .mess import MyClass, MyOtherClass
__all_exports = [MyClass, MyOtherClass]
for e in __all_exports:
e.__module__ = __name__
__all__ = [e.__name__ for e in __all_exports]
This seems to have worked pretty well for me.
I would like to provide a more generalized approach.
The variable __all__ is filled up based on dir(). But the sub-packages name (here mypackage) and all in-build attributes (starting with __) are ignored.
from .mypackage import *
__all__ = []
for v in dir():
if not v.startswith('__') and v != 'mypackage':
__all__.append(v)
Short answer: You shouldn't. Just point the sphinx to the directory of your code. Sphinx documents the code and shows the module hirarchy. How the module finally will be imported is purely in the hand of the developer, but not a responsibility of the documentation tool.
I have some python modules containing mostly functions and a few classes. Each one is documented using sphinx-autodoc in a separate rst. What I want to do is to create a table or list of the module's contents at the top of each page, so for example, of mymodule.py is
def first():
'First function'
def second():
'Second function'
And mymodule.rst is
Page Contents
-------------
:create_page_contents_list:
Members
-------
.. automodule:: mymodule
:members:
Then the output should look something like this:
Page Contents
-------------
first
second
Members
-------
first()
First function
second()
Second function
The question how to do :create_page_contents_list:. I've have a look at using a TOC, but it seems that I would need to manually create an entry for each item. I've also looked at autosummary, but I still need to list the members. Any suggestions for automating this? I'd rather avoid third-party extensions.
You probably want something like the autosummary extension. The actual autosummary extension will not quite do what you want, though.
An example of how you might extend autosummary to auto-detect the contents of the module is given in this answer
I have installed Sphinx in order to document some Python modules and class I'm working on. While the markup language looks very nice, I haven't managed to auto-document a Python code.
Basically, I have the following Python module:
SegLib.py
And A class called Seg in it. I would like to display the docstrings of the class and module within the generated Sphinx document, and add further formatted text to it.
My index.rst looks like this:
Contents:
.. toctree::
:maxdepth: 2
chapter1.rst
and chapter1.rst:
This is a header
================
Some text, *italic text*, **bold text**
* bulleted list. There needs to be a space right after the "*"
* item 2
.. note::
This is a note.
See :class:`Seg`
But Seg is just printed in bold, and not linked to an auto-generated documentation of the class.
Trying the following didn't help, either:
See :class:`Seg`
Module :mod:'SegLib'
Module :mod:'SegLib.py'
Edit: changed SegLib to segments (thanks, iElectric!), and changed chapter1.rst to:
The :mod:`segments` Module
--------------------------
.. automodule:: segments.segments
.. autoclass:: segments.segments.Seg
Still, can't get Sphinx to directly document functions within a class, or better - to automatically add all the functions within a class to the document. Tried:
.. autofunction:: segments.segments.Seg.sid
and got:
autodoc can't import/find function 'segments.segments.Seg.sid', it reported error: "No module named Seg"
Any ideas how to auto-document the functions and classes with a short command?
Add to the beginning of the file:
.. module:: SegLib
Try using :autoclass: directive for class doc.
BTW: module names should be lower_case.
EDIT: I learned a lot from reading other source files.