Example sphinx project using autodoc
This commit is contained in:
commit
de73e1a27b
|
@ -0,0 +1,2 @@
|
||||||
|
__pycache__/
|
||||||
|
docs-out/
|
|
@ -0,0 +1,51 @@
|
||||||
|
# Example project
|
||||||
|
|
||||||
|
Simple example that hopefully demonstrates how to use sphinx in autodoc.
|
||||||
|
|
||||||
|
Map of important files:
|
||||||
|
- `docs/` -- Where all docs-related content is kept. It doesn't have to be in
|
||||||
|
its own folder, but it's a common convention.
|
||||||
|
|
||||||
|
- `conf.py` -- The configuration file for sphinx. See this file for more
|
||||||
|
details on how to configure Sphinx for use with autodoc.
|
||||||
|
|
||||||
|
- `index.rst` -- Root document that will become `index.html` in the generated
|
||||||
|
docs. It's conventional to put a `toctree` or at least some links to other
|
||||||
|
pages in the docs here.
|
||||||
|
|
||||||
|
- `module.rst` -- Where the autodoc for the example module is invoked.
|
||||||
|
|
||||||
|
- `src/` -- Where all the Python sources are kept. Also not a requirement to
|
||||||
|
have them separate, but a convention.
|
||||||
|
|
||||||
|
- `module/` -- The example module (in this case, a folder-type module with an
|
||||||
|
`__init__.py` specifying the exported names).
|
||||||
|
|
||||||
|
- `__init__.py` -- Entry point for the module specifying the exported
|
||||||
|
symbols. Sphinx autodoc uses this to figure out what parts of the module
|
||||||
|
to add to the docs.
|
||||||
|
|
||||||
|
- `module_class.py` -- Defines the Example class used to showcase the
|
||||||
|
autodoc features.
|
||||||
|
|
||||||
|
- `simple.py` -- A simple file-style module with a couple more exported names.
|
||||||
|
|
||||||
|
## Running Sphinx
|
||||||
|
|
||||||
|
First, make sure Sphinx is installed.
|
||||||
|
|
||||||
|
```
|
||||||
|
python3 -m pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
Then, you can generate the docs:
|
||||||
|
|
||||||
|
```
|
||||||
|
sphinx-build -b html docs/ docs-out
|
||||||
|
```
|
||||||
|
|
||||||
|
And view them in your browser:
|
||||||
|
|
||||||
|
```
|
||||||
|
xdg-open docs-out/index.html
|
||||||
|
```
|
|
@ -0,0 +1,15 @@
|
||||||
|
# Basic project metadata. This is used when generating the doc pages for things
|
||||||
|
# like titles and footers.
|
||||||
|
project = "Example"
|
||||||
|
|
||||||
|
# This doc becomes `index.html` in the generated html docs
|
||||||
|
master_doc = "index"
|
||||||
|
|
||||||
|
# Sphinx autodoc will need to be able to import our module. Augmenting
|
||||||
|
# `sys.path` with the path to the module ensures it can find it when we invoke
|
||||||
|
# autodoc from a documentation file.
|
||||||
|
import sys, os
|
||||||
|
sys.path.append(os.path.join(os.path.dirname(__file__), "../src"))
|
||||||
|
|
||||||
|
# Enable the autodoc extension
|
||||||
|
extensions = ["sphinx.ext.autodoc"]
|
|
@ -0,0 +1,6 @@
|
||||||
|
Welcome to the Example docs!
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
simple
|
||||||
|
module
|
||||||
|
|
|
@ -0,0 +1,8 @@
|
||||||
|
Documentation for ``module``
|
||||||
|
====================================
|
||||||
|
|
||||||
|
Module is an example module that demonstrates the use of ``Autodoc``.
|
||||||
|
|
||||||
|
.. automodule:: module
|
||||||
|
:members:
|
||||||
|
|
|
@ -0,0 +1 @@
|
||||||
|
sphinx
|
|
@ -0,0 +1,15 @@
|
||||||
|
More info
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
Here's a second file which could provide some detail on a particular module,
|
||||||
|
class, or concept.
|
||||||
|
|
||||||
|
It can include specific function docs here:
|
||||||
|
|
||||||
|
.. autofunction:: math.log
|
||||||
|
|
||||||
|
And here's the docs for our second module:
|
||||||
|
|
||||||
|
.. automodule:: simple
|
||||||
|
:members:
|
||||||
|
|
|
@ -0,0 +1,3 @@
|
||||||
|
from .module_class import *
|
||||||
|
|
||||||
|
__all__ = ["Example", "MODULE_CONST"]
|
|
@ -0,0 +1,20 @@
|
||||||
|
import sys
|
||||||
|
import os
|
||||||
|
|
||||||
|
|
||||||
|
MODULE_CONST = 1
|
||||||
|
|
||||||
|
|
||||||
|
class Example:
|
||||||
|
"""This is an example class which uses python docstrings to document itself.
|
||||||
|
|
||||||
|
It lives in :module:.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def foo(self, amount):
|
||||||
|
"""Applies the well known ``foo`` operation to an instance of
|
||||||
|
:Example:.
|
||||||
|
|
||||||
|
:param: amount: How much foo to do.
|
||||||
|
"""
|
||||||
|
self.amount = amount
|
|
@ -0,0 +1,8 @@
|
||||||
|
|
||||||
|
__all__ = ["SIMPLE_CONST", "bar"]
|
||||||
|
|
||||||
|
SIMPLE_CONST = 2
|
||||||
|
|
||||||
|
def bar(a, b):
|
||||||
|
"""Returns whether :a: and :b: have passed the bar exam in their state."""
|
||||||
|
return a + b > SIMPLE_CONST
|
Loading…
Reference in New Issue