Sphinx Python Documentation Generator Indira Gutierrez Michal Ondrejcek

Sphinx Python Documentation Generator Indira Gutierrez Michal Ondrejcek

Useful Commands Function Command Installation pip install sphinx Setup sphinx-quickstart Running the build Sphinx-build –b html sourcedir builddir Make html

Required Setup In. /docs/source/conf. py sys. path. insert(0, os. path. abspath('. . /. . ')) sys. path. insert(0, os. path. abspath('. . /pygeotemporal'))

Index. rst Note How the == need to be the exact length as the title Special format for inline hyperlink `Link text <http: //example. com/> Names of additional files to be included

Modules. rst Insert a Table of Contents tree with max depth 4 (The level of which it will include the kids table contents) Names of additional files to be included

Pyclowder. rst Automodule: Document whole classes. Members: Automatically document members, can also be a list of selected members to document Undoc-members: Add this option to include members that don’t have docstring Show-inheritance: With this option, a list of base classes will be inserted just below the class signature

Source Code Docstring that will get added to documentation

Output

Generated Documentation

Documentation Site http: //www. sphinx-doc. org/en/stable/contents. html

Example: MDF Forge Sphinx uses external pre-processor that parses Num. Py and Google style docstrings and converts them to re. Structured. Text spaces important bold

Example: MDF Forge generated documentation

Parse. txt, . md, . rst and. ipynb files Pandoc is a universal document converter, converting from one markup format into another and from markup to document formats From To (several dialects of) Markdown, re. Structured. Text, textile, HTML, Doc. Book, La. Te. X, Media. Wiki markup, Tiki. Wiki markup, Creole 1. 0, Vimwiki markup, OPML, Emacs Org-Mode, Emacs Muse, txt 2 tags, Microsoft Word docx, Libre. Office ODT, EPUB, or Haddock markup • HTML formats XHTML, HTML 5, and HTML slide shows using Slidy, reveal. js, Slideous, S 5, or DZSlides • Word processor formats Microsoft Word docx, Open. Office/Libre. Office ODT, Open. Document XML, Microsoft Power. Point. • Ebooks EPUB version 2 or 3, Fiction. Book 2 • Documentation formats Doc. Book version 4 or 5, TEI Simple, GNU Tex. Info, Groff man, Groff ms, Haddock markup • Archival formats JATS • Page layout formats In. Design ICML • Outline formats OPML • Te. X formats La. Te. X, Con. Te. Xt, La. Te. X Beamer slides • PDF via pdflatex, xelatex, lualatex, pdfroff, wkhtml 2 pdf, prince, or weasyprint. • Lightweight markup formats Markdown (including Common. Mark and Git. Hub-flavored Markdown), re. Structured. Text, Ascii. Doc, Emacs Org-Mode, Emacs Muse, Textile, txt 2 tags, Media. Wiki markup, Doku. Wiki markup, Tiki. Wiki markup, TWiki markup, Vimwiki markup, and Zim. Wiki markup. • Custom formats custom writers can be written in lua.

conf. py add source code

conf. py You can use Markdown and re. Structured. Text in the same Sphinx project. Markdown doesn’t support a lot of the features of Sphinx, like inline markup and directives. However, it works for basic prose content. re. Structured. Text is the preferred format for technical documentation

conf. py Napoleon is a Sphinx extensions that enables Sphinx to parse both Num. Py and Googlestyle docstrings

‘examples’ ipynb files not linked ‘examples’ ipynb files linked Linked Markdown and Jupyter files ‘tutorials’ md files not linked

Read the Docs Create, host, and browse documentation. Automatic import from external account • Connect to your Git. Hub or Bitbucket account first • Authorize a connection to Read the Docs, it enables Read the Docs to configure your repository webhooks automatically. Manual Import • Type your repository URL • Manually configure the repository webhook. Repository webhook triggers builds for your project on Read the Docs upon new changeset. https: //readthedocs. org/