Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Intro to Documentation using Sphinx and reStructuredText

6b6e72d297aa0270654a0d4575f1287e?s=47 Mariatta
February 19, 2021

Intro to Documentation using Sphinx and reStructuredText

Presented at Pyninsula Meetup Feb 23, 2021.

6b6e72d297aa0270654a0d4575f1287e?s=128

Mariatta

February 19, 2021
Tweet

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 ![alt text](/path/to/image.jpg) 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