Browse Source

Example sphinx project using autodoc

main
khr 2 years ago
commit
de73e1a27b
  1. 2
      .gitignore
  2. 51
      README.md
  3. 15
      docs/conf.py
  4. 6
      docs/index.rst
  5. 8
      docs/module.rst
  6. 1
      docs/requirements.txt
  7. 15
      docs/simple.rst
  8. 3
      src/module/__init__.py
  9. 20
      src/module/module_class.py
  10. 8
      src/simple.py

2
.gitignore vendored

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

51
README.md

@ -0,0 +1,51 @@ @@ -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

@ -0,0 +1,15 @@ @@ -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

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

8
docs/module.rst

@ -0,0 +1,8 @@ @@ -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

@ -0,0 +1 @@ @@ -0,0 +1 @@
sphinx

15
docs/simple.rst

@ -0,0 +1,15 @@ @@ -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

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

20
src/module/module_class.py

@ -0,0 +1,20 @@ @@ -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

@ -0,0 +1,8 @@ @@ -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…
Cancel
Save