I'm documenting a method, and one of its parameters needs to be of a particular class. I therefore have the following code inside the method's docstring:
.. autoclass:: mymodule.classnumberone
:members:
:exclude-members: Schema
This works fine. But the trouble is, I'm calling that same method through a variety of paths, and the class of the parameter changes depending on the path. One time it needs to be mymodule.classnumbertwo, mymodule.classnumberthree, etc.
I've tried each of the following but none of them work:
.. autoclass:: mymodule.|classnumberone|
:members:
:exclude-members: Schema
and
.. autoclass:: |moduleplusclass|
:members:
:exclude-members: Schema
and
|entire autoclass directive|
and
.. autoclass:: mymodule.classnumber|num|
:members:
:exclude-members: Schema
Each attempt, of course, is paired with the appropriate substitution directive on the pages that calls this method, such as .. |moduleplusclass| replace:: mymodule.classnumberone and .. |moduleplusclass| replace:: mymodule.classnumberone, or .. |entire autoclass directive| autoclass:: mymodule.classnumberone etc.
None of these work. It appears that it is resolving autoclass before it is resolving the substitution directive. Is there any way to accomplish what I'm trying to do here?
Related
I have a block of code in a file that I want to include in an example in Sphinx documentation, using a literalinclude directive.
But that code is in a function, so when I include it, in the example each line is indented by one level more than I'd like.
.. literalinclude:: ../../examples/example.py
:language: python
:lines: 13-42
:tab-width: 0
Produces
import foo
from foo import bar
print("I'm indented too far")
Is there any other way to remove or deindent the literal block?
literalinclude has a dedent option:
.. literalinclude:: ../../examples/example.py
:language: python
:lines: 13-42
:tab-width: 0
:dedent: 4
The option is mentioned under "Additional options" in the literalinclude documentation, but the details are in the documentation for code-block.
If I have a file foo.baz.py:
from foo.bar.baz import Quux, Quuux
__all__ = ['Quux', 'Quuux']
I'd like to document the api as follows:
Baz
===
.. currentmodule:: foo.baz
.. autosummary::
:toctree: generated/
:nosignatures:
Quux
Quuux
This gives me an autosummary table with Quux and Quuux, and links to pages containing their full documentation. However, it requires me to explicitly list Quux and Quuux, so whenever I add a class, I have to manually add it to the documentation.
Instead, I'd rather like to do something like this, and have it automatically generate a table based on __all__, to get exactly the same output as above:
Baz
===
.. currentmodule:: foo
.. autosummary::
:toctree: generated/
:nosignatures:
baz
But this doesn't work, it produces a table with a single entry, the module baz, leading to a page with all its contents as well as a summary table.
Is there a way to achieve this? In case it's relevant, I'm using numpydoc.
I installed the sphinxcontrib-plantuml extension which works fine if I run the HTML builder e.g. with following testmodule.rst file for a corresponding testmodule.py file:
testmodule module
=================
.. automodule:: testmodule
:members:
:undoc-members:
:show-inheritance:
.. uml::
Alice -> Bob: Hi!
Alice <- Bob: How are you?
This adds the UML diagram at the very end of the document. Unfortunately I didn't find out how to embed a UML diagram anywhere in the documentation e.g. somewhere in the middle of a methods docstring block.
Does anyone know how to do that?
Adding the UML diagram directly in the docstring section didn't work for me.
But following worked for me:
Put plantuml code in separate file e.g. diagram.uml:
#startuml
Alice -> Bob: Hi!
Alice <- Bob: How are you?
#enduml
Add the plantuml directive with the filename at the desired place in the docstring. E.g.:
def example():
"""
some text
.. uml:: diagram.uml
some more text
"""
...
I'm trying to have a variable in conf.py that inserts a link that is applied on a string:
rst_epilog = """
.. |support| replace:: `support team <support#blabla.com>`_
"""
In this case 'support team' would turn into a link pointing to the email address.
Unfortunately, this does not work and the build breaks.
So I've tried dumping HTML in there, not knowing when the substitution happens, but it happens before HTML conversion, so that does not work in my output.
rst_epilog = """
.. |support| replace:: support team
"""
Any idea I could do this with a variable?
Use this substitution definition:
.. |support| replace:: support team support#blabla.com
support#blabla.com is automatically recognized as a mailto link.
The |support| substitution reference produces the following output:
support team <a class="reference external" href="mailto:support%40blabla.com">support<span>#</span>blabla<span>.</span>com</a>
An alternative is to use a raw-html role (see http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw).
Add this to conf.py:
rst_epilog = """
.. role:: raw-html(raw)
:format: html
.. |support| replace:: :raw-html:`support team`
"""
I'd like to be able to author footnotes at the point where they are referenced, but then only have them display at the end of the document, where .. rubric: Footnotes appears.
Like this:
Lorem Ipsum[#lorem]_ dolor sit blah blah.
.. [#lorem]
The footnote text here.
The next paragraph. Salve regina mater misericordiae, vita dulcedo.
.. rubric: Footnotes
DESIRED OUTPUT:
Lorem Ipsum^1 dolor sit blah blah.
The next paragraph. Salve regina mater misericordiae, vita dulcedo.
Footnotes:
1 The footnote text here.
According to the docutils docs this should be possible:
Footnotes may occur anywhere in the document, not only at the end.
Where and how they appear in the processed output depends on the
processing system.
But I can't find how to make the processing system (Sphinx, using the built-in make html) put them only at the bottom, instead of wherever they appear.
I've used the footnote approach, however, you must be careful about where you're placing the refs. So, my modules.rst look like this:
Brief
-----
.. automodule:: modules
:members:
:undoc-members:
:show-inheritance:
Sub modules
-----------
.. toctree::
:maxdepth: 4
modules.ahp
modules.grid
Plot module
-------------------
.. automodule:: modules.Plot
:members:
:undoc-members:
:show-inheritance:
Score module
-------------------
.. automodule:: modules.Score
:members:
:undoc-members:
:show-inheritance:
Skillset module
-------------------
.. automodule:: modules.Skillset
:members:
:undoc-members:
:show-inheritance:
util module
-------------------
.. automodule:: modules.util
:members:
:undoc-members:
:show-inheritance:
|hr|
.. rubric:: Footnotes
.. [#euclidian] `Wikipedia <https://en.wikipedia.org/wiki/Dot_product#Geometric_definition>`_
Since that my utils module contains the function where I'm using the footnote, it works like the expected. (It just creates a reference to a div in the current page)