Practical Sphinx - Speaker Deck

Slide 1

Slide 1 text

Practical Sphinx Practical Sphinx Carol Willing PyCon 2018 @WillingCarol 1

Slide 2

Slide 2 text

practical practical the actual doing ... rather than with theory and ideas likely to succeed or be eﬀective in real circumstances Source: Oxford Dictionary 2

Slide 3

Slide 3 text

Challenges Challenges 3

Slide 4

Slide 4 text

People People Opinions 4

Slide 5

Slide 5 text

Tools Tools Scalpel Sledgehammer Sphinx ??? 5

Slide 6

Slide 6 text

Processes Processes Reduce Reuse Recycle 6

Slide 7

Slide 7 text

Time Time Eﬃciency 7

Slide 8

Slide 8 text

Slide 9

Slide 9 text

I needed a plan. I needed a plan. 9

Slide 10

Slide 10 text

Get practical Get practical 10

Slide 11

Slide 11 text

Why Why 11

Slide 12

Slide 12 text

Roadmap Roadmap 12

Slide 13

Slide 13 text

Basics Basics Basics 13

Slide 14

Slide 14 text

python3 m pip install Sphinx Install Install 14

Slide 15

Slide 15 text

mkdir project cd project sphinxquickstart . Use the defaults. Create Create 15

Slide 16

Slide 16 text

Key files Key files conf.py index.rst Makefile 16

Slide 17

Slide 17 text

conf.py settings execute code 17

Slide 18

Slide 18 text

make clean make build Build Build 18

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

Basics Words Words Words 20

Slide 21

Slide 21 text

Source format Source format , Markdown, or Notebooks reStructuredText 21

Slide 22

Slide 22 text

No changes to conf.py No changes to conf.py reStructuredText .rst reStructuredText .rst 22

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

pandoc pandoc convert all the formats https://pandoc.org/ https://pandoc.org/try/ pandoc test1.md f markdown t rst o test1.rst 26

Slide 27

Slide 27 text

drafts drafts Just write Content ﬁrst, quality later 27

Slide 28

Slide 28 text

re-read read aloud Grammarly Spell check Editing Editing Excellent resource The Responsible Communication Style Guide by Thursday Bram 28

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

Basics Visuals Visuals Words Visuals 30

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

image image (rendered) (rendered) 32

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

directives directives (rendered) (rendered) 34

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

code code (rendered) 36

Slide 37

Slide 37 text

Basics Structure Structure Words Visuals Structure 37

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

.. 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

Slide 41

Slide 41 text

Basics Workflow Workflow Words Visuals Structure Workﬂow 41

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

Travis CI Travis CI Automate Automate GitHub Webhooks GitHub Webhooks 43

Slide 44

Slide 44 text

Host at ReadTheDocs Host at ReadTheDocs Use yaml ﬁle in project's root. readthedocs.yml name: nbgrader type: sphinx requirements_file: requirements.txt python: version: 3 setup_py_install: true 44

Slide 45

Slide 45 text

Monitoring Monitoring 45

Slide 46

Slide 46 text

Slide 47

Slide 47 text

Basics Extensions Extensions Words Visuals Structure Workﬂow Extensions 47

Slide 48

Slide 48 text

===== 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

Slide 49

Slide 49 text

Title Text Title Text (rendered) sphinx.ext.autodoc 49

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

Sphinx, JavaScript Sphinx, JavaScript and and Beautiful Design Beautiful Design 52

Slide 53

Slide 53 text

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

Slide 54

Slide 54 text

JavaScript JavaScript Beautiful themes Sphinx-js Autodoc extension for JavaScript https://pypi.org/project/sphinx-js/ Simpler tools More diﬃcult to link between and within docs 54

Slide 55

Slide 55 text

Themes Themes Another built-in theme Default (Alabaster) A third party theme import and set conﬁguration parameters (conf.py) 55

Slide 56

Slide 56 text

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

Slide 57

Slide 57 text

Practical Plan Practical Plan likely to succeed or be eﬀective in real circumstances 57

Slide 58

Slide 58 text

Use sensible defaults Use sensible defaults 58

Slide 59

Slide 59 text

Configure Configure conf.py 59

Slide 60

Slide 60 text

Step by step Step by step Basics Words Visuals Structure Workﬂow Extensions 60

Slide 61

Slide 61 text

Iterate Iterate 61

Slide 62

Slide 62 text

Do your best Do your best Docs matter for your project's success. Get installation right. Automate your workﬂow. 62