Currently I do this:
conf.py:
autosummary_generate = True
reference.rst:
package_1
---------
.. autosummary::
:toctree: _generated
package_1.module_1
package_1.module_2
package_1.module_3
...
This will generate an overview table for each module, with entries for each module
that nicely link to detail pages.
I have two questions:
Do I really have to enumerate every single module?
How can I control the options of the detail pages?
Ad 1.:
I would like to do s.th like this (which currently doesn't work):
.. autosummary:: package_1
:toctree: _generated
:members:
(Or maybe a new autopackage command.)
Ad 2.:
I would like to pass options like the ones that automodule or autoclass expect, e.g.:
.. autosummary::
:toctree: _generated
:undoc-members:
:private-members:
This seems to be an obvious task, so I am probably missing some information.
Is there an easy alternative way to accomplish this?
Thanks to all commenters!
Ad 1:
I list the modules manually.
Ad 2:
I finally went with the solution proposed by this and this answers to similar questions:
Create template files (_templates/autosummary/module.rst and _templates/autosummary/class.rst) and add this to
api_doc.rst:
Package ``wsgidav``
-------------------
.. autosummary::
:toctree: _autosummary
wsgidav._version
wsgidav.compat
Related
I have modules I'd like to document such that the table of contents is on the main page index and the documentations themselves are in separate pages. I'm new to automatic documentation and Sphinx, but I've gotten close:
index.rst:
Documentation
*************
.. toctree::
:maxdepth: 2
Module1
Module2
Index
=====
* :ref:`genindex`
* :ref:`modindex`
Module1.rst and Module2.rst:
Title
*****
.. automodule:: Module1 (or Module2)
:noindex:
:members:
The reason for using noindex was getting duplicate object description errors. However this prevents the modules from showing up on the toctree of index. How might this be avoided? It seems like a basic thing one would do but I can't get my head around it.. Any help would be greatly appreciated!
It seems this question and its answer attempts to address a similar problem, but I don't think it's quite the same, as the OP commented on the answer.
I typically put the high-level documentation for a Python package into the docstring of its __init__.py file. This makes sense to me, given that the __init__.py file represents the package's interface with the outside world. (And, really, where else would you put it?)
So, I was really quite surprised when I fired up Sphinx for the first time and saw this content buried near the very end of the package documentation, after the content for all of the submodules.
This seems backward to me. The very first thing the user will see when he visits the page for a package is the documentation of the submodule that just happens to come first alphabetically, and the thing he should see first is right near the bottom.
I wonder if there is a way to fix this, to make the stuff inside of __init__.py come out first, before all of the stuff in the submodules. And if I am just going about this in the wrong way, I want to know that. Thanks!
Updated Answer (thank you, Donal Fellows):
https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html#cmdoption-sphinx-apidoc-M
Original Answer:
Yes, there is an option to do this, it's just not documented here. Inside my copy of Sphinx-1.3.3/sphinx/apidoc.py I found this:
parser.add_option('-M', '--module-first', action='store_true',
dest='modulefirst',
help='Put module documentation before submodule '
'documentation')
I tried it and it works like a charm.
It is also possible to add this option in the conf.py file.
Search in conf.py for the line where the string containing the sphinx-apidoc command is (located in a try section) and add the "--module-first" option.
The new line will look like this:
cmd_line_template = "sphinx-apidoc --module-first -f -o {outputdir} {moduledir}"
Hadn't used Sphinx in a while, but it does seem like they've done a good job updating it. In the past, I had to manually specify the classes since I didn't like how autodoc generated the methods/functions. Now it does seem like you can order them:
.. autoclass:: YourClass
:members: __init__, __getitem__
http://www.sphinx-doc.org/en/stable/ext/autodoc.html
How to insert a cross-reference in a reST/Sphinx page to either a sub-header or anchor in another page in the same documentation set?
The expression "reST/Sphinx" makes the scope of the question unclear. Is it about reStructuredText in general and Sphinx, or only about reStructuredText as used in Sphinx (and not reStructuredText in general)? I'm going to cover both since people using RST are likely to run into both cases at some point:
Sphinx
Besides the domain-specific directives that can be used to link to various entities like classes (:class:) there's the general :ref: directive, documented here. They give this example:
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
Although the general hyperlinking mechanism offered by RST does work in Sphinx, the documentation recommends against using it when using Sphinx:
Using ref is advised over standard reStructuredText links to sections (like Section title_) because it works across files, when section headings are changed, and for all builders that support cross-references.
RST, in General
The tools that convert RST files to HTML do not necessarily have a notion of collection. This is the case for instance if you rely on github to convert RST files to HTML or if you use a command line tool like rst2html. Unfortunately, the various methods to use to get the desired result vary depending on which tool you are using. For instance, if you use rst2html and you want file A.rst to link to a section named "Section" in file other.rst and you want the final HTML to work in a browser, then A.rst would contain:
`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.
You have to link to the final HTML file and you have to know what the id given to the section will be. If you want to do the same for a file served through github:
`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.
Here too you need to know the id given to the section. However, you link to the RST file because it is only upon accessing the RST file that the HTML is created. (At the time of writing this answer, accessing the HTML directly is not allowed.)
A complete example is available here.
New, better answer for 2016!
The autosection extension lets you do this easily.
=============
Some Document
=============
Internal Headline
=================
then, later...
===============
Some Other Doc
===============
A link- :ref:`Internal Headline`
This extension is built-in, so all you need is to edit conf.py
extensions = [
.
. other
. extensions
. already
. listed
.
'sphinx.ext.autosectionlabel',
]
The only thing you have to be careful of is that now you can't duplicate internal headlines across the doc collection. (Worth it.)
Example:
Hey, read the :ref:`Installation:Homebrew` section.
where Homebrew is a section inside a different document named Installation.rst.
This uses the autosection feature, so will need to edit config.py with the following:
extensions = [
'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
In Sphinx 3.0.3 the only solution that worked for me is :any: (see https://www.sphinx-doc.org/en/1.5/markup/inline.html#cross-referencing-anything).
Suppose, one document has such a section:
.. _my-section:
My Section
----------
Lorem ipsum blablabla
Then another document can have the following fragment to create a link:
See :any:`my-section` for the details
I was struggling to make this work and i found out that the actual notation is :ref:'{dir-path}/Installation:Homebrew' where {dir-path} is the relative path to Installation.rst from where config.py exists
Adding description of behavior that was confusing to me.
Section titles must be referenced with the file name (overview here) in front of it:
overview.rst:
************
API Overview
************
index.rst:
:ref:`overview:API Overview`
However, when referencing links, the file name (constants here) must not be there:
constants.rst:
.. _section-constants:
*******************
Enums and Constants
*******************
api.rst:
:ref:`section-constants`
Also, for this to work, one must enable extension 'autosectionlabel':
conf.py:
extensions = [
...
"sphinx.ext.autosectionlabel"
]
I have a module with several classes. Currently I am using ..automodule to document the module. I'd like each class to have its own header section with the class name. I could achieve this by replacing ..automodule foo with:
Bar
===
..autoclass foo.Bar
Baz
===
..autoclass foo.Baz
...
However, that would require me to manually list every class in every module I do this for. What is the best way to customize the content generated by automodule?
Sphinx is not as straightforward to use as Epydoc or Doxygen for generating API documentation from source code. It is a dfferent kind of tool.
Sphinx works on .rst (reStructuredText) files, and if you want each class to have its own heading with the class name, you have to add the headings yourself and use .. autoclass::. It cannot be done with just .. automodule::. Yes, this is inconvenient (similar sentiments are expressed here). See also this answer and this answer.
The problem can be mitigated by a script that walks through the Python code and generates .rst output. Sphinx already comes with such a script, sphinx-apidoc. However, it does not produce any .. autoclass:: directives, only .. automodule::.
Here is another script that can output .. autoclass::: https://github.com/PyMVPA/PyMVPA/blob/master/tools/apigen.py. Maybe you can use that.
I have the following page at plugins/index.html:
Plugin Development
==================
.. toctree::
:hidden:
basics/index
advanced/index
The Basics
----------
- :doc:`basics/gettingstarted`
- :doc:`basics/resources`
- :doc:`basics/i18n`
Advanced Topics
---------------
- :doc:`advanced/models`
- :doc:`advanced/controllers`
- :doc:`advanced/services`
plugin/basics/index.html and plugins/advanced/index.html contain their own toctree’s, which link to the same subpages listed in plugins/index.html. So what I’m wondering is, is there a way to just include those sub toctree’s, rather than manually listing the sub pages out like I’m doing?
I realize that I could just remove the :hidden: flag from the toctree, but the point is I want to keep Basic/Advanced topics in separate lists, with their own headings, intro paragraphs, etc.
You can list the entire directory contents like this (or various combinations of these directives):
.. toctree::
:glob:
:titlesonly:
:maxdepth: 2
**
or I think also like this (untested):
.. toctree::
:glob:
:titlesonly:
:maxdepth: 2
*
basics/*
advanced/*
However, I have found just manually listing things is often the best way to go. While the automatically generated TOCs are nice, they don't allow you much room in terms of formatting (for example, creating sub headings, and changing the order of pages etc).
In our documentation I have done pretty much the same thing you did in the initial question.