I am using Sphinx to document a python project. The documentation includes both an API reference and a user guide. I would like to include links from the user guide to the relevant section of the API reference, but can't seem to figure it out.
My API refrence uses the autodoc extension; however, I list my methods out individually, e.g.:
.. automodule:: module_name
.. autoclass:: class_name
.. automethod:: method_a
.. automethod:: method_b
In another rst file I have my user guide. I can link to an arbitrary place in another rst file using ref; however, it seems that the lable must come before a section title. So for instance the below doesn't work.
userguide.rst
see :ref:`my-reference-label` for more details on method_b
api.rst
.. automodule:: module_name
.. autoclass:: class_name
.. automethod:: method_a
.. _my-reference-label:
.. automethod:: method_b
How can a link to a specific place in my API documentation?
You don't need to define a label. A hyperlink to method_b can be created using the :py:meth: role:
:py:meth:`module_name.class_name.method_b`
This markup can be customized and simplified in various ways (for example, the :py prefix is not necessary when the domain is Python).
More details here:
http://sphinx-doc.org/markup/inline.html#cross-referencing-syntax
http://sphinx-doc.org/domains.html#cross-referencing-python-objects
Related
Problem
To fully use the autodoc potential, I want to document my code with something like:
.. automodule :: mymodule
However, mymodule is made of a class that has it's own documenter. One of my project's dependencies created a subclass of sphinx.ext.autodoc.ClassDocumenter that documents a class it provides. My mymodule is made up of classes derived from that base one. The custom documenter has an option I want to use, how do I provide it while using automodule?
Alternative formulation
Another case that I think is the same problem:
.. automodule :: mymodule
.. automodule :: myothermodule
These two modules are made of classes that will be documented with autoclass. I want to activate the ":inherited-members:" option for classes of the first mymodule but not on the ones of myothermodule. Is this possible?
I have a comment in my python module that documents several classes that follow, e.g.
###
# Classes for agents: patients and clinicians
###
class EngagementLadder(transitions.Machine):
"""The state machine for agent states.
In fact there are several such multi-class comments. Each serves to break up the file, together organizing it into related sections.
I would like to see those comments in the generated documentation, perhaps as headers. How to do that?
Note that my question is similar to In Sphinx, how to include docstrings/comments located in a module, but outside of class and methods, but the answer that worked for him---putting it in the module docstring---will not work for me as I want these comments further down the file.
One method of achieving this is to use dummy variables
I.e. The below will add a section heading
SECTION_A = "SECTION A"
"""Section A contains some useful stuff about my project...
It can span multiple lines...
"""
def foo():
"""Description of foo"""
pass
#: Section B contains some useful stuff about my project...
#: It can span multiple lines
SECTION_B = "SECTION B"
def bar():
"""Description of foo"""
pass
Documentation here: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoattribute
Is it possible do disable the complete autosummary when using autodoc?
I've got a class derived from a Python standard library class, which has many public methods. My custom class should work as a wrapper, directly providing methods to communicate with my device using its protocol.
Therefore I only want to include a few selected inherited methods in the autosummary table.
.. autoclass:: my_module.MyClass
:members:
:show-inheritance:
.. autosummary::
my_method
another_method
The ..autosummary:: block does exactly what I desire, but ..autoclass:: automatically creates a full methods table. Is there a way to disable this feature?
Edit (clarification)
Using the autosummary directive directly, I'm able to produce a method table containing only my_method and another_method:
.. autosummary::
my_method
another_method
However, when using autoclass or automodule without a following autosummary directive, I still get a method table looking exactly like the one created by the autosummary block above, only with all methods described:
.. autoclass:: my_module.MyClass
:members:
:show-inheritance
Edit 2
The "complete" autosummary table is being generated by numpydoc.
The "problem" was not inside autodoc or autosummary.
Though not mentioned in the question I'm using numpydoc, which was generating the additional autosummary table.
As described in numpydoc's documentation, this feature can be disabled by adding numpydoc_show_inherited_class_members = False to the sphinx conf.py.
You can remove the :members: tag, or include a comma separated list after :members: of only the methods you want to include in your documentation.
I am using middleman for building an API description web page, and I wonder if it is possible to define methods somewhere which will be used to parse YAML in desired format, basically I am looking for the place where I can put my helper methods
I put mine in the config.rb inside a helpers block, e.g.
helpers do
def emphasise word
word ?
"<em>#{word}</em>" :
word
end
def bracket word
word ?
"(#{word})" :
word
end
end
That helper will then be in scope for use in a template.
Edit: I found the section of the docs for defining custom helpers
I want to write some documentation in the module which should be at one point of my documentation. At this point I don't want to document all the classes/members of the module. This can be easily done with
..automodule:: myModule
:no-members:
However, at another point of my documentation I want to document all the classes of myModule. I could do this with
..automodule:: myModle
:members:
:noindex:
Unfortunately, this also includes the documentation of the module itself which I already have in my documentation and which I don't want to have here, again.
Is there a way to show only the documentation of all the members of myModule but not the documentation of myModule itself without having to list all the members manually?
Thanks to the comments I was able to solve the problem. Adding the following lines to conf.py does the trick:
def remove_module_docstring(app, what, name, obj, options, lines):
if what == "module" and name == "hpclogging.logger" and 'members' in options:
del lines[:]
def setup(app):
app.connect("autodoc-process-docstring", remove_module_docstring)