Documentation with Sphinx
Download as PPTX, PDF0 likes478 views
The document outlines a workflow for documenting with Sphinx using reStructuredText (RST) to create HTML, detailing the formatting options and basic syntax of RST. It highlights the importance of using plain-text editors for authoring, the use of Sphinx for conversion, and provides resources for setting up a Python virtual environment and installing necessary packages. Additional best practices for source control with Git are also discussed, along with links to relevant documentation and tools.
![Resources
• Down & Install Python - No need to learn Python!
• https://www.python.org/downloads/
• Download & Install GIT [this also provides Linux shell on Windows]
• https://git-scm.com/downloads
• Create and activate virtual env
• https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments
• Install Sphinx from pypi
• pip install -U sphinx
• https://www.sphinx-doc.org/en/master/usage/installation.html#installation-from-
pypi
• Install RTD Theme
• pip install sphinx_rtd_theme
• https://pypi.org/project/sphinx-rtd-theme/
• Theme config: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html](https://image.slidesharecdn.com/documentation-with-sphinx-201021100721/85/Documentation-with-Sphinx-11-320.jpg)
![Resources
• Setup documentation source structure
• sphinx-quickstart
• https://www.sphinx-doc.org/en/master/usage/quickstart.html#setting-up-
the-documentation-sources
• Build Configuration file [conf.py]
• The file is generated with documentation source structure
• Options in file have include description
• https://www.sphinx-doc.org/en/master/usage/configuration.html
• Building [converting RST to HTML]
• sphinx-build sourcedir builddir
• https://www.sphinx-doc.org/en/master/usage/quickstart.html#running-the-
build](https://image.slidesharecdn.com/documentation-with-sphinx-201021100721/85/Documentation-with-Sphinx-12-320.jpg)
Documentation with Sphinx
- 1. Documenting with Sphinx ReStructured Text to HTML
- 2. Authoring Workflow Write RST using any 'text' editor Compile RST to HTML using Sphinx Host HTML using any web server
- 3. ReStructured Text • A plain text format • Also known as RST • Authored using plain-text editors • Markdown is used for formatting • Compiles into HTML • Intro to simple formatting options at https://en.wikipedia.org/wiki/ReStructuredText#Ex amples_of_reST_markup
- 4. Basic Formatting First Heading ============= Sub-heading ----------- Third Heading ~~~~~~~~~~~~~ Paragraphs are separated by a blank line. Two spaces at the end of a line produces a line break. *text* for emphasis (italics) **text** for strong emphasis (boldface) ``text`` for code samples. * this is * a list * with a nested list * and some subitems * and here the parent list continues 1. This is a numbered list. 2. It has two items too. #. This is a numbered list. #. It has two items too.
- 5. More Formatting .. This is a comment. .. This whole indented block is a comment. Still in the comment. .. image:: path/to/image.png .. raw:: html <div>This is raw HTML</div> This is a paragraph that contains `a link`_. .. _a link: https://domain.invalid/ :: some literal text This may also be used inline at the end of a paragraph, like so:: some more literal text
- 6. Tables +------------------------+------------+----------+----------+ | Header row, column 1 | Header 2 | Header 3 | Header 4 | | (header rows optional) | | | | +========================+============+==========+==========+ | body row 1, column 1 | column 2 | column 3 | column 4 | +------------------------+------------+----------+----------+ | body row 2 | ... | ... | | +------------------------+------------+----------+----------+ ===== ===== ======= A B A and B ===== ===== ======= False False False True False False False True False True True True ===== ===== ======= Other supported Table formats: CSV Table: https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table List Table: https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table
- 7. Cautions Use a plain-text editor only • Notepad++, Vim etc. 1 Don’t use WYSIWYG editors • MS word, textEdit, Notepad etc. 2 Use uniform underlines for headings in all files 3 Keep track for indentation, whitespace & blank-lines in rst file 4
- 8. Sphinx • Tool that converts rst to HTML • Multiple skins (themes) available • Plugins available for extending • Complete list of formatting options supported by sphinx https://www.sphinx- doc.org/en/master/usage/restructuredtext/basics.html
- 9. One-time Setup Customize customize conf.py Create Create Documentation Structure Install Install required Sphinx plugins e.g. rtdtheme Install Install Sphinx in virtual env Create Create Python virtual env (best practice) Install Install Python
- 10. Additional Best Practice – Use GIT • Version control source files • rst files • conf.py • GIT is common version control system • Keeps the data safe • Allows to pull old versions • Allow seamless collaboration More about source control and Git at https://www.slideshare.net/AkshayMathur7/git-workshop-26088242
- 11. Resources • Down & Install Python - No need to learn Python! • https://www.python.org/downloads/ • Download & Install GIT [this also provides Linux shell on Windows] • https://git-scm.com/downloads • Create and activate virtual env • https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments • Install Sphinx from pypi • pip install -U sphinx • https://www.sphinx-doc.org/en/master/usage/installation.html#installation-from- pypi • Install RTD Theme • pip install sphinx_rtd_theme • https://pypi.org/project/sphinx-rtd-theme/ • Theme config: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html
- 12. Resources • Setup documentation source structure • sphinx-quickstart • https://www.sphinx-doc.org/en/master/usage/quickstart.html#setting-up- the-documentation-sources • Build Configuration file [conf.py] • The file is generated with documentation source structure • Options in file have include description • https://www.sphinx-doc.org/en/master/usage/configuration.html • Building [converting RST to HTML] • sphinx-build sourcedir builddir • https://www.sphinx-doc.org/en/master/usage/quickstart.html#running-the- build