Codebase for the UShER wiki.
pip install -r requirements.txt
cd docs
make linkcheck
make html
Docs will be created in a new folder named build
, and you can clean up afterwards with make clean
.
:ref:
or :doc:
to make a relative path to the page rather than making a hyperlink to the absolute URL, which may change over time. See sphinx's docs on how to use those.
:orphan:
and :hidden:
for example)document isn't included in any toctree
-- "toctree" is the table-of-contents sidebar which appears on the left when the docs are compiled. If you want the file to appear in this sidebar, add it to the toctree declaration in index.rst. If you don't want it to end up on the sidebar, add :orphan:
plus a blank newline at the top of the document.
toctree
declaration not only builds the sidebar on the left hand side of the webpage, it also will create a table of contents in the body of the text itself. The docs currently use the :hidden:
declaration to hide this body-toc -- note that :hidden:
does not hide the sidebar toc.Title underline too short
-- RST is picky about this, just roll with it.Duplicate explicit target name
-- this is another weird RST quirk, which can be solved by including two underscores instead of one when referencing other pageslinkcheck
, so if you have an external link that you know is working, but it can't pass linkcheck, just add the URL to linkcheck_ignore in conf.py