Example sphinx project using autodoc

This commit is contained in:
khr 2020-07-20 21:58:39 -07:00
commit de73e1a27b
10 changed files with 129 additions and 0 deletions

2
.gitignore vendored Normal file
View File

@ -0,0 +1,2 @@
__pycache__/
docs-out/

51
README.md Normal file
View File

@ -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
```

15
docs/conf.py Normal file
View File

@ -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"]

6
docs/index.rst Normal file
View File

@ -0,0 +1,6 @@
Welcome to the Example docs!
.. toctree::
simple
module

8
docs/module.rst Normal file
View File

@ -0,0 +1,8 @@
Documentation for ``module``
====================================
Module is an example module that demonstrates the use of ``Autodoc``.
.. automodule:: module
:members:

1
docs/requirements.txt Normal file
View File

@ -0,0 +1 @@
sphinx

15
docs/simple.rst Normal file
View File

@ -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:

3
src/module/__init__.py Normal file
View File

@ -0,0 +1,3 @@
from .module_class import *
__all__ = ["Example", "MODULE_CONST"]

View File

@ -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

8
src/simple.py Normal file
View File

@ -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