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

Intro to Documentation using Sphinx and reStruc...

Mariatta
February 19, 2021

Intro to Documentation using Sphinx and reStructuredText

Presented at Pyninsula Meetup Feb 23, 2021.

Mariatta

February 19, 2021
Tweet

More Decks by Mariatta

Other Decks in Programming

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. 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
  3. 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
  4. 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
  5. 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
  6. reStructuredText Intro to Documentation using Sphinx and reStructuredText Markdown @mariatta

    Section header ============== # Section Header ## Subsection Header Subsection header ----------------- Headers
  7. Section header ============== # Section Header ## Subsection Header Subsection

    header ----------------- @mariatta Intro to Documentation using Sphinx and reStructuredText
  8. 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
  9. 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
  10. 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
  11. 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
  12. 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
  13. 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
  14. 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
  15. 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
  16. 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
  17. 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
  18. 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
  19. 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
  20. 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