52 lines
1.5 KiB
Markdown
52 lines
1.5 KiB
Markdown
# 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
|
|
```
|