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.

Transcript

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
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 conf.py index.rst Makefile 16
17. conf.py 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 conf.py No changes to conf.py 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'] conf.py 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'] conf.py 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 markdown_doc.md notebook.ipynb index.rst 25
26. pandoc pandoc convert all the formats https://pandoc.org/ https://pandoc.org/try/ pandoc test1.md ­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 conf.py 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 <https://github.com/data-8/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 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
36. code code (rendered) 36
37. Basics Structure Structure Words Visuals Structure 37
38. toctree toctree Add Add structure structure your docs. your docs. 38
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 43
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
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', ] conf.py 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', ] conf.py 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' ] conf.py 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 52
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 https://pypi.org/project/sphinx-js/ 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 (conf.py) 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 conf.py 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
64. Thank you Thank you @WillingCarol https://speakerdeck.com/willingc 64