34bbb3ad32
Summary: Applies new import merging and sorting from µsort v1.0. When merging imports, µsort will make a best-effort to move associated comments to match merged elements, but there are known limitations due to the diynamic nature of Python and developer tooling. These changes should not produce any dangerous runtime changes, but may require touch-ups to satisfy linters and other tooling. Note that µsort uses case-insensitive, lexicographical sorting, which results in a different ordering compared to isort. This provides a more consistent sorting order, matching the case-insensitive order used when sorting import statements by module name, and ensures that "frog", "FROG", and "Frog" always sort next to each other. For details on µsort's sorting and merging semantics, see the user guide: https://usort.readthedocs.io/en/stable/guide.html#sorting Reviewed By: bottler Differential Revision: D35553814 fbshipit-source-id: be49bdb6a4c25264ff8d4db3a601f18736d17be1
Setup
Install dependencies
pip install -U recommonmark mock 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... /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/