Sphinx Python Documentation Generator - PowerPoint Presentation

1. Sphinx Python Documentation GeneratorIndira GutierrezMichal Ondrejcek

2. Useful CommandsFunctionCommandInstallationpip install sphinxSetupsphinx-quickstartRunning the buildSphinx-build –b html sourcedir builddirMake html

3. Required SetupIn ./docs/source/conf.pysys.path.insert(0, os.path.abspath('../..'))sys.path.insert(0, os.path.abspath('../../pygeotemporal'))

4. Index.rstNote How the == need to be the exact length as the titleSpecial format for inline hyperlinks:`Link text <http://example.com/>`_Names of additional files to be included

5. Modules.rstNames of additional files to be includedInsert a Table of Contents tree with max depth 4 (The level of which it will include the kids table contents)

6. Pyclowder.rstAutomodule: Document whole classes.Members: Automatically document members, can also be a list of selected members to documentUndoc-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

7. Source CodeDocstring that will get added to documentation

8. Output

9. Generated Documentation

10. Documentation Sitehttp://www.sphinx-doc.org/en/stable/contents.html

11. Example: MDF Forgeboldspaces importantSphinx uses external pre-processor that parses NumPy and Google style docstrings and converts them to reStructuredText

12. Example: MDF Forge generated documentation

13. Parse .txt, .md, .rst and .ipynb filesPandoc is a universal document converter, converting from one markup format into another and from markup to document formatsFromTo(several dialects of) Markdown, reStructuredText, textile, HTML, DocBook, LaTeX, MediaWiki markup, TWiki markup, TikiWiki markup, Creole 1.0, Vimwiki markup, OPML, Emacs Org-Mode, Emacs Muse, txt2tags, Microsoft Word docx, LibreOffice ODT, EPUB, or Haddock markupHTML formats XHTML, HTML5, and HTML slide shows using Slidy, reveal.js, Slideous, S5, or DZSlidesWord processor formats Microsoft Word docx, OpenOffice/LibreOffice ODT, OpenDocument XML, Microsoft PowerPoint.Ebooks EPUB version 2 or 3, FictionBook2Documentation formats DocBook version 4 or 5, TEI Simple, GNU TexInfo, Groff man, Groff ms, Haddock markupArchival formats JATSPage layout formats InDesign ICMLOutline formats OPMLTeX formats LaTeX, ConTeXt, LaTeX Beamer slidesPDF via pdflatex, xelatex, lualatex, pdfroff, wkhtml2pdf, prince, or weasyprint.Lightweight markup formats Markdown (including CommonMark and GitHub-flavored Markdown), reStructuredText, AsciiDoc, Emacs Org-Mode, Emacs Muse, Textile, txt2tags, MediaWiki markup, DokuWiki markup, TikiWiki markup, TWiki markup, Vimwiki markup, and ZimWiki markup.Custom formats custom writers can be written in lua.

14. conf.pyadd source code

15. conf.pyYou can use Markdown and reStructuredText 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. reStructuredText is the preferred format for technical documentation

16. conf.pyNapoleon is a Sphinx extensions that enables Sphinx to parse both NumPy and Googlestyle docstrings

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

18. Read the DocsCreate, host, and browse documentation.https://readthedocs.org/Automatic import from external accountConnect to your GitHub or Bitbucket account firstAuthorize a connection to Read the Docs, it enables Read the Docs to configure your repository webhooks automatically.Manual ImportType your repository URLManually configure the repository webhook.Repository webhook triggers builds for your project on Read the Docs upon new changeset.