Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

Sphinx reStructuredText @mariatta Intro to Documentation using Sphinx and reStructuredText

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

Images reStructuredText ![alt text](/path/to/image.jpg) Markdown .. image:: /path/to/image.jpg @mariatta Intro to Documentation using Sphinx and reStructuredText

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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