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


  1. Practical Sphinx Practical Sphinx Carol Willing PyCon 2018 @WillingCarol 1

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

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

  4. People People Opinions 4

  5. Tools Tools Scalpel Sledgehammer Sphinx ??? 5

  6. Processes Processes Reduce Reuse Recycle 6

  7. Time Time Efficiency 7

  8. 8

  9. I needed a plan. I needed a plan. 9

  10. Get practical Get practical 10

  11. Why Why 11

  12. Roadmap Roadmap 12

  13. Basics Basics Basics 13

  14. python3 ­m pip install Sphinx Install Install 14

  15. mkdir project cd project sphinx­quickstart . Use the defaults. Create

    Create 15
  16. Key files Key files index.rst Makefile 16

  17. settings execute code 17

  18. make clean make build Build Build 18

  19. python3 ­m http.server Serve Serve http://localhost:8000/_build/html/index.html 19

  20. Basics Words Words Words 20

  21. Source format Source format , Markdown, or Notebooks reStructuredText 21

  22. No changes to No changes to reStructuredText .rst

    reStructuredText .rst 22
  23. 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'] 23
  24. 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'] 24
  25. 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 notebook.ipynb index.rst 25
  26. pandoc pandoc convert all the formats pandoc

    ­f markdown ­t rst ­o test1.rst 26
  27. drafts drafts Just write Content first, quality later 27

  28. re-read read aloud Grammarly Spell check Editing Editing Excellent resource

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

    else: extensions.append("sphinxcontrib.spelling") spelling_word_list_filename='wordlist.txt' make spelling 29
  30. Basics Visuals Visuals Words Visuals 30

  31. 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
  32. image image (rendered) (rendered) 32

  33. 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 <>`_ prior to using the tool in production. .. warning:: 33
  34. directives directives (rendered) (rendered) 34

  35. code code 1. Let's add the JupyterHub. .. code:: bash

    helm repo add jupyterhub 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
  36. code code (rendered) 36

  37. Basics Structure Structure Words Visuals Structure 37

  38. toctree toctree Add Add structure structure your docs. your docs.

  39. toctree toctree .. toctree:: :maxdepth: 2 installation config_options changelog 39

  40. .. 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
  41. Basics Workflow Workflow Words Visuals Structure Workflow 41

  42. make linkcheck Valid links Valid links make build Build errors

    Build errors Testing Testing 42
  43. Travis CI Travis CI Automate Automate GitHub Webhooks GitHub Webhooks

  44. 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
  45. Monitoring Monitoring 45

  46. 46

  47. Basics Extensions Extensions Words Visuals Structure Workflow Extensions 47

  48. ===== 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', ] Autodocument using docstrings 48
  49. Title Text Title Text (rendered) sphinx.ext.autodoc 49

  50. napoleon napoleon sphinx.ext. sphinx.ext. extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.intersphinx',

    'sphinx.ext.autosummary', 'sphinx.ext.mathjax', 'nbsphinx', ] Parse Google or Numpy style docstrings 50
  51. 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' ] Set path to directory of third party extension Add extension to the list of extensions 51
  52. Sphinx, JavaScript Sphinx, JavaScript and and Beautiful Design Beautiful Design

  53. 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
  54. JavaScript JavaScript Beautiful themes Sphinx-js Autodoc extension for JavaScript

    Simpler tools More difficult to link between and within docs 54
  55. Themes Themes Another built-in theme Default (Alabaster) A third party

    theme import and set configuration parameters ( 55
  56. 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
  57. Practical Plan Practical Plan likely to succeed or be effective

    in real circumstances 57
  58. Use sensible defaults Use sensible defaults 58

  59. Configure Configure 59

  60. Step by step Step by step Basics Words Visuals Structure

    Workflow Extensions 60
  61. Iterate Iterate 61

  62. Do your best Do your best Docs matter for your

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

  64. Thank you Thank you @WillingCarol 64