Intro to Documentation using Sphinx and reStructuredText

Presented at Pyninsula Meetup Feb 23, 2021.

Transcript

1. Intro to Documentation using Sphinx and reStructuredText Staff Software Engineer at Uplight Python Core Developer PyLadies Vancouver co-organizer PSF Fellow @mariatta Mariatta Wijaya Mariatta Wijaya
2. … or It Doesn’t Exist Docs @mariatta Intro to Documentation using Sphinx and reStructuredText
3. Sphinx reStructuredText @mariatta Intro to Documentation using Sphinx and reStructuredText
4. reStructuredText Is a markup language (like Markdown and HTML) Not as lightweight Markdown Virtually unknown outside of Python community (*.rst) @mariatta Intro to Documentation using Sphinx and reStructuredText
5. Sphinx Is a Documentation Generator Converts .rst into .html files … and other formats like PDF, EPub, etc @mariatta Intro to Documentation using Sphinx and reStructuredText
6. reStructuredText Is a markup language (like Markdown and HTML) Not as lightweight Markdown Virtually unknown outside of Python community @mariatta Intro to Documentation using Sphinx and reStructuredText
7. Used in Python since 2002 reStructuredText Intro to Documentation using Sphinx and reStructuredText Did not exist until 2004 Markdown PEP 287 Python Docs and PEPs are written in it @mariatta
8. reStructuredText Intro to Documentation using Sphinx and reStructuredText Markdown @mariatta Section header ============== # Section Header ## Subsection Header Subsection header ----------------- Headers
9. Section header ============== # Section Header ## Subsection Header Subsection header ----------------- @mariatta Intro to Documentation using Sphinx and reStructuredText
10. Links reStructuredText Download [Python](https://python.org) now. Markdown Download `Python <https://python.org>`_ now. @mariatta Intro to Documentation using Sphinx and reStructuredText
11. Named links reStructuredText Download [Python](https://python.org) now, because [Python](https://python.org) is a popular programming language. Markdown Download `Python`_ now, because `Python`_ is a popular programming language. .. _Python: https://python.org @mariatta Intro to Documentation using Sphinx and reStructuredText
12. Images reStructuredText  Markdown .. image:: /path/to/image.jpg @mariatta Intro to Documentation using Sphinx and reStructuredText
13. Code blocks reStructuredText ``` from datetime import datetime print(f"{date time.now():%Y-%m-%d}”) ``` Markdown :: from datetime import datetime print(f”{datetime.now():%Y-%m-%d}") @mariatta Intro to Documentation using Sphinx and reStructuredText
14. Tables reStructuredText Not supported natively Markdown ========== ====== ======= Fruit Color Price ========== ====== ======= Banana Yellow 40¢/kg Gala Apple Red 70¢/kg Lime Green 57¢/kg ========== ====== ======= @mariatta Intro to Documentation using Sphinx and reStructuredText
15. Table of Contents reStructuredText .. contents:: Details: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents Not supported natively Markdown Example: https://github.com/Mariatta/buildmydocs/blob/main/README.rst @mariatta Intro to Documentation using Sphinx and reStructuredText
16. Cross-referencing reStructuredText + Sphinx .. _install-guide: Installation Guide ================== 1. Create and activate a virtual env 2. ``pip install`` it For details on how to install, please read :ref:`install-guide`. installation.rst index.rst @mariatta Intro to Documentation using Sphinx and reStructuredText
17. Cross-referencing reStructuredText + Sphinx .. _install-guide: Installation Guide ================== 1. Create and activate a virtual env 2. ``pip install`` it For details on how to install, please read :ref:`install-guide`. installation.rst index.rst target @mariatta Intro to Documentation using Sphinx and reStructuredText
18. Cross-referencing reStructuredText + Sphinx .. _install-guide: Installation Guide ================== 1. Create and activate a virtual env 2. ``pip install`` it For details on how to install, please read :ref:`install-guide`. installation.rst index.rst target reference @mariatta Intro to Documentation using Sphinx and reStructuredText
19. python3 -m venv .env source .env/bin/activate python3 -m pip install sphinx Get Started with Sphinx @mariatta Intro to Documentation using Sphinx and reStructuredText
20. Get Started with Sphinx sphinx-quickstart Finished: An initial directory structured has been created @mariatta Intro to Documentation using Sphinx and reStructuredText mkdir docs cd docs
21. Get Started with Sphinx /docs/ /docs/_build/ /docs/_static/ /docs/_templates/ /docs/conf.py /docs/index.rst /docs/make.bat /docs/Makefile @mariatta Intro to Documentation using Sphinx and reStructuredText
22. Build the Docs make html The HTML pages are in _build/html. /docs/_build/html/index.html @mariatta Intro to Documentation using Sphinx and reStructuredText
23. sphinx-autobuild python3 -m pip install sphinx-autobuild sphinx-autobuild docs docs/_build/html @mariatta Intro to Documentation using Sphinx and reStructuredText
24. Sphinx extensions `sphinx.ext.autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_ Automatically include documentation from docstrings @mariatta Intro to Documentation using Sphinx and reStructuredText `sphinx.ext.intersphinx <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_ Link to other projects’ documentation
25. Learn More .. _reStructuredText Primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _Get started with Sphinx: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html .. _reStructuredText markup specification: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html @mariatta Intro to Documentation using Sphinx and reStructuredText
26. Thanks! .. Sponsor on GitHub: https://github.com/sponsor/Mariatta Intro to Documentation using Sphinx and reStructuredText @Mariatta