Sphinx apidoc usage: Difference between revisions
From wikinotes
(Created page with "<syntaxhighlight lang="bash"> # generate apidocs (before `make html`) sphinx-apidoc \ --separate \ -d 3 \ -o ./_api \ project/path </syntaxhighlight>") |
No edit summary |
||
Line 1: | Line 1: | ||
= Build = | |||
<blockquote> | |||
<syntaxhighlight lang="bash"> | <syntaxhighlight lang="bash"> | ||
# generate apidocs (before `make html`) | # generate apidocs (before sphinx's `make html`) | ||
sphinx-apidoc \ | sphinx-apidoc \ | ||
--separate \ | --separate \ | ||
Line 7: | Line 9: | ||
project/path | project/path | ||
</syntaxhighlight> | </syntaxhighlight> | ||
</blockquote><!-- Build --> | |||
= Code = | |||
<blockquote> | |||
== preparing your code == | |||
<blockquote> | |||
If you want a clean representation of your codebase, make sure that you | |||
follow python's conventions for public/private classes, functions, methods, | |||
and modules. | |||
<syntaxhighlight lang="python"> | |||
## private functions, methods, classes, python-modules | |||
## will not be documented by default | |||
## | |||
def _private_func(): | |||
pass | |||
class _PrivateClass(object): | |||
pass | |||
</syntaxhighlight> | |||
If you import modules into your <code>__init__.py</code>, modules included | |||
in the __all__ variable will be documented in sphinx as members. | |||
<syntaxhighlight lang="python"> | |||
from .mymodule import * | |||
__all__ = [ | |||
'function_from_mymodule', | |||
'function_from_mymodule2', | |||
] | |||
</syntaxhighlight> | |||
If you are trying to hide a module from sphinx make it a private module | |||
by adding 2x underscores to it's name. (even if there are public callables | |||
within it, they will not appear in sphinx). | |||
<syntaxhighlight lang="python"> | |||
#### /path/to/package/__mymodule.py | |||
def public_function(): | |||
pass | |||
</syntaxhighlight> | |||
</blockquote><!-- preparing your code --> | |||
== documenting your code == | |||
<blockquote> | |||
There are a handful of different ways of documenting your code, I've been | |||
using the napoleon extension, whose syntax I have covered in greater detail below. | |||
Generally speaking though, your doctags will look like this: | |||
<syntaxhighlight lang="python"> | |||
def some_func(): | |||
""" | |||
A description of your function | |||
Args: | |||
car_brand (str): ``(ex: 'Honda', 'Toyota', ...)`` | |||
The Manufacturer of your car | |||
car_type (str): ``(ex: 'Sedan', 'SUV', ...)`` | |||
The type of car you have | |||
colour Optional([str]): ``(ex: 'red', 'green', 'plaid', ...)`` | |||
The colour of your car. | |||
available_materials (obj): | |||
:type: :py:obj:`path.to.pkg.MyObject` | |||
An object that stores the available materials. | |||
Attributes: | |||
fuel_remaining (float): The fuel left in the tank | |||
durability(float): The remaining durability of the car | |||
.. versionadded:: 3.6 | |||
.. versionchanged:: 3.6 | |||
Returns: | |||
.. code-block:: python | |||
A dictionary with your car's info. | |||
""" | |||
pass | |||
</syntaxhighlight> | |||
</blockquote><!-- documenting your code --> | |||
</blockquote><!-- Code --> |
Revision as of 12:44, 4 July 2022
Build
# generate apidocs (before sphinx's `make html`) sphinx-apidoc \ --separate \ -d 3 \ -o ./_api \ project/path
Code
preparing your code
If you want a clean representation of your codebase, make sure that you follow python's conventions for public/private classes, functions, methods, and modules.
## private functions, methods, classes, python-modules ## will not be documented by default ## def _private_func(): pass class _PrivateClass(object): pass
If you import modules into your__init__.py
, modules included in the __all__ variable will be documented in sphinx as members.from .mymodule import * __all__ = [ 'function_from_mymodule', 'function_from_mymodule2', ]If you are trying to hide a module from sphinx make it a private module by adding 2x underscores to it's name. (even if there are public callables within it, they will not appear in sphinx).
#### /path/to/package/__mymodule.py def public_function(): passdocumenting your code
There are a handful of different ways of documenting your code, I've been using the napoleon extension, whose syntax I have covered in greater detail below.
Generally speaking though, your doctags will look like this:
def some_func(): """ A description of your function Args: car_brand (str): ``(ex: 'Honda', 'Toyota', ...)`` The Manufacturer of your car car_type (str): ``(ex: 'Sedan', 'SUV', ...)`` The type of car you have colour Optional([str]): ``(ex: 'red', 'green', 'plaid', ...)`` The colour of your car. available_materials (obj): :type: :py:obj:`path.to.pkg.MyObject` An object that stores the available materials. Attributes: fuel_remaining (float): The fuel left in the tank durability(float): The remaining durability of the car .. versionadded:: 3.6 .. versionchanged:: 3.6 Returns: .. code-block:: python A dictionary with your car's info. """ pass