| ## Setup | |
| ### Install dependencies | |
| ``` | |
| pip install -U recommonmark sphinx sphinx_rtd_theme sphinx_markdown_tables | |
| ``` | |
| ### Add symlink to the root README.md | |
| We want to include the root readme as an overview. Before generating the docs create a symlink to the root readme. | |
| ``` | |
| cd docs | |
| ln -s ../README.md overview.md | |
| ``` | |
| In `conf.py` for deployment this is done using `subprocess.call`. | |
| ### Add a new file | |
| Add a new `.md` or `.rst` file and add the name to the doc tree in `index.rst` e.g | |
| ``` | |
| .. toctree:: | |
| :maxdepth: 1 | |
| :caption: Intro Documentation | |
| overview | |
| ``` | |
| To autogenerate docs from docstrings in the source code, add the import path for the function e.g. | |
| ``` | |
| Chamfer Loss | |
| -------------------- | |
| .. autoclass:: loss.chamfer.chamfer_distance | |
| :members: | |
| :undoc-members: | |
| .. automethod:: __init__ | |
| ```` | |
| ### Build | |
| From `pytorch3d/docs` run: | |
| ``` | |
| > make html | |
| ``` | |
| The website is generated in `_build/html`. | |
| ### Common Issues | |
| Sphinx can be fussy, and sometimes about things you weren’t expecting. For example, you might encounter something like: | |
| WARNING: toctree contains reference to nonexisting document u'overview' | |
| ... | |
| checking consistency... | |
| <pytorch3d>/docs/overview.rst:: | |
| WARNING: document isn't included in any toctree | |
| You might have indented overview in the .. toctree:: in index.rst with four spaces, when Sphinx is expecting three. | |
| ### View | |
| Start a python simple server: | |
| ``` | |
| > python -m http.server | |
| ``` | |
| Navigate to: `http://0.0.0.0:8000/` | |