57f6e79280
Summary: Something's wrong with recommonmark/CommonMark/six, let's see if this fixes it. https://readthedocs.org/projects/pytorch3d/builds/21292632/ ``` File "/home/docs/checkouts/readthedocs.org/user_builds/pytorch3d/envs/latest/lib/python3.11/site-packages/sphinx/config.py", line 368, in eval_config_file execfile_(filename, namespace) File "/home/docs/checkouts/readthedocs.org/user_builds/pytorch3d/envs/latest/lib/python3.11/site-packages/sphinx/util/pycompat.py", line 150, in execfile_ exec_(code, _globals) File "/home/docs/checkouts/readthedocs.org/user_builds/pytorch3d/checkouts/latest/docs/conf.py", line 25, in <module> from recommonmark.parser import CommonMarkParser File "/home/docs/checkouts/readthedocs.org/user_builds/pytorch3d/envs/latest/lib/python3.11/site-packages/recommonmark/parser.py", line 6, in <module> from CommonMark import DocParser, HTMLRenderer File "/home/docs/checkouts/readthedocs.org/user_builds/pytorch3d/envs/latest/lib/python3.11/site-packages/CommonMark/__init__.py", line 3, in <module> from CommonMark.CommonMark import HTMLRenderer File "/home/docs/checkouts/readthedocs.org/user_builds/pytorch3d/envs/latest/lib/python3.11/site-packages/CommonMark/CommonMark.py", line 18, in <module> HTMLunescape = html.parser.HTMLParser().unescape ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ AttributeError: 'HTMLParser' object has no attribute 'unescape' ``` Reviewed By: shapovalov Differential Revision: D47471545 fbshipit-source-id: 48e121e20da535b3cc46b6bd2393d28869067b8b
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... /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/