12. Sphinx and reStructuredText¶
12.1. Sphinx¶
12.1.1. Bugs and Features¶
./mkdoc will not delete a build html file after the source rst file has been deleted!!!!
toctree Error Message - Pycharm, both professional and community edition uses docutils to parse Sphinx documentation. Docutils does not recognize toctree
12.1.2. Links for sphinx¶
a ‘Sphinxdocumention <https://www.sphinx-doc.org/en/master/contents.html>’_
this is a paragraph that contains ‘a link’_. .. _a link: https://www.sphinx-doc.org/en/master/contents.html
<https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html>
12.2. reStructured Text¶
12.2.1. Links¶
Excellent source of major points of reStructuredText https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html.
Use backtick “`” when creating a label for a link. It appears you should also also use a backtick when creating a standalone link but an apostrophe. “’” seems to work.
Heroku has an excellent on-line ‘Online Sphinx Editor’ https://livesphinx.herokuapp.com/ where you can play with getting reStructuredText working correctly
12.2.2. Lists¶
Use ‘*’ for an unordered list
This is a list
It has two items, the second item uses two lines
third item
second item
Use ‘#.’ for a numbered list
a numbered list
second item
12.2.3. Sections¶
# with overline for parts
* with overline for sections
= for sections
- for subsections
^ for subsubsections
” for paragraphs