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

… or It Doesn’t Exist Docs @mariatta Intro to Documentation using Sphinx and reStructuredText

Sphinx reStructuredText @mariatta Intro to Documentation using Sphinx and reStructuredText

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

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

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

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

reStructuredText Intro to Documentation using Sphinx and reStructuredText Markdown @mariatta Section header ============== # Section Header ## Subsection Header Subsection header ----------------- Headers

Section header ============== # Section Header ## Subsection Header Subsection header ----------------- @mariatta Intro to Documentation using Sphinx and reStructuredText

Links reStructuredText Download [Python](https://python.org) now. Markdown Download `Python `_ now. @mariatta Intro to Documentation using Sphinx and reStructuredText

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

Images reStructuredText  Markdown .. image:: /path/to/image.jpg @mariatta Intro to Documentation using Sphinx and reStructuredText

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

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

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

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

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

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

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

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

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

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

sphinx-autobuild python3 -m pip install sphinx-autobuild sphinx-autobuild docs docs/_build/html @mariatta Intro to Documentation using Sphinx and reStructuredText

Sphinx extensions `sphinx.ext.autodoc `_ Automatically include documentation from docstrings @mariatta Intro to Documentation using Sphinx and reStructuredText `sphinx.ext.intersphinx `_ Link to other projects’ documentation

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

Thanks! .. Sponsor on GitHub: https://github.com/sponsor/Mariatta Intro to Documentation using Sphinx and reStructuredText @Mariatta