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

Practical Sphinx

Practical Sphinx

PyCon 2018.
Learn how to integrate documentation into your everyday development workflow, apply best practices, and use modern development tools and services, like Travis CI and ReadTheDocs, to create engaging and up-to-date documentation
which users and contributors will love.

Carol Willing

May 12, 2018

More Decks by Carol Willing

Other Decks in Technology


  1. practical practical the actual doing ... rather than with theory

    and ideas likely to succeed or be effective in real circumstances Source: Oxford Dictionary 2
  2. 8

  3. Markdown: use recommonmark Markdown: use recommonmark # For conversion from

    markdown to html import recommonmark.Parser # Add a source file parser for markdown source_parsers = { '.md': 'recommonmark.parser.CommonMarkParser', } # Add type of source files source_suffix = ['.rst', '.md'] conf.py 23
  4. Jupyter notebooks: use Jupyter notebooks: use nbsphinx nbsphinx extension extension

    extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.autosummary', 'sphinx.ext.mathjax', 'nbsphinx', ] # Add type of source files source_suffix = ['.rst', '.md', '.ipynb'] conf.py 24
  5. Contents with multiple formats Contents with multiple formats Minimal docs

    ============ You can mix and match source formats. .. toctree:: :maxdepth: 2 :caption: Contents: sample_doc.rst markdown_doc.md notebook.ipynb index.rst 25
  6. re-read read aloud Grammarly Spell check Editing Editing Excellent resource

    The Responsible Communication Style Guide by Thursday Bram 28
  7. Spelling extension Spelling extension try: import sphinxcontrib.spelling except ImportError: pass

    else: extensions.append("sphinxcontrib.spelling") spelling_word_list_filename='wordlist.txt' make spelling conf.py 29
  8. image image The following diagram gives a high-level overview of

    the many pieces of JupyterHub, and how they fit together in this process: .. image:: _static/images/architecture.png :align: center .. image:: filename 31
  9. directives directives for more information on using this tool. ..

    warning:: ``nbgitpuller`` will attempt to automatically resolve merge conflicts if your user's repository has changed since the last sync. You should familiarize yourself with the `nbgitpuller merging behavior <https://github.com/data-8/nbgitpuller#merging-behavior>`_ prior to using the tool in production. .. warning:: 33
  10. code code 1. Let's add the JupyterHub. .. code:: bash

    helm repo add jupyterhub https://jupyterhub.github.io/helm-chart/ helm repo update This should show output like: .. code:: Hang tight while we grab the latest from your chart repositories... ...Skip local chart repository ...Successfully got an update from the "stable" chart repository ...Successfully got an update from the "jupyterhub" chart repository Update Complete. ⎈ Happy Helming! ⎈ .. code:: 35
  11. .. toctree:: :titlesonly: :caption: Step Zero: your Kubernetes cluster create-k8s-cluster

    google/step-zero-gcp microsoft/step-zero-azure amazon/step-zero-aws redhat/step-zero-openshift Captions Captions 40
  12. Host at ReadTheDocs Host at ReadTheDocs Use yaml file in

    project's root. readthedocs.yml name: nbgrader type: sphinx requirements_file: requirements.txt python: version: 3 setup_py_install: true 44
  13. 46

  14. ===== Users ===== Module: :mod:`jupyterhub.user` ============================== .. automodule:: jupyterhub.user ..

    currentmodule:: jupyterhub.user :class:`UserDict` ----------------- .. autoclass:: UserDict :members: :class:`User` ------------- .. autoclass:: User :members: escaped_name .. attribute:: name The user's name .. attribute:: server users.rst sphinx.ext.autodoc sphinx.ext.autodoc extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.autosummary', 'sphinx.ext.mathjax', 'nbsphinx', ] conf.py Autodocument using docstrings 48
  15. napoleon napoleon sphinx.ext. sphinx.ext. extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.intersphinx',

    'sphinx.ext.autosummary', 'sphinx.ext.mathjax', 'nbsphinx', ] conf.py Parse Google or Numpy style docstrings 50
  16. Third party extensions Third party extensions import sys, os sys.path.append(os.path.abspath('sphinxext'))

    ... extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'autodoc_traits' ] conf.py Set path to directory of third party extension Add extension to the list of extensions 51
  17. Sphinx Sphinx Great support for navigation in docs Nice integration

    with RTD Helpful communities - Sphinx and Write The Docs Active responsive developers on Sphinx project 53
  18. Themes Themes Another built-in theme Default (Alabaster) A third party

    theme import and set configuration parameters (conf.py) 55
  19. Customize your Theme Customize your Theme Create your own theme

    Recommended only if you have the time to maintain it. Extend or create Jinja2 templates Customize CSS 56
  20. Do your best Do your best Docs matter for your

    project's success. Get installation right. Automate your workflow. 62
  21. 63