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
Tweet

More Decks by Carol Willing

Other Decks in Technology

Transcript

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

    View full-size slide

  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

    View full-size slide

  3. Challenges
    Challenges
    3

    View full-size slide

  4. People
    People
    Opinions
    4

    View full-size slide

  5. Tools
    Tools
    Scalpel
    Sledgehammer
    Sphinx
    ???
    5

    View full-size slide

  6. Processes
    Processes
    Reduce
    Reuse
    Recycle
    6

    View full-size slide

  7. Time
    Time
    Efficiency
    7

    View full-size slide

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

    View full-size slide

  9. Get practical
    Get practical
    10

    View full-size slide

  10. Roadmap
    Roadmap
    12

    View full-size slide

  11. Basics
    Basics
    Basics
    13

    View full-size slide

  12. python3 ­m pip install Sphinx
    Install
    Install
    14

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  15. conf.py
    settings
    execute code
    17

    View full-size slide

  16. make clean
    make build
    Build
    Build
    18

    View full-size slide

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

    View full-size slide

  18. Basics
    Words
    Words
    Words
    20

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  25. drafts
    drafts
    Just write
    Content first, quality later
    27

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  28. Basics
    Visuals
    Visuals
    Words Visuals
    30

    View full-size slide

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

    View full-size slide

  30. image
    image
    (rendered)
    (rendered)
    32

    View full-size slide

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

    View full-size slide

  32. directives
    directives
    (rendered)
    (rendered)
    34

    View full-size slide

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

    View full-size slide

  34. code
    code
    (rendered)
    36

    View full-size slide

  35. Basics
    Structure
    Structure
    Words Visuals
    Structure
    37

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  39. Basics
    Workflow
    Workflow
    Words Visuals
    Structure Workflow
    41

    View full-size slide

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

    View full-size slide

  41. Travis CI
    Travis CI
    Automate
    Automate
    GitHub Webhooks
    GitHub Webhooks
    43

    View full-size slide

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

    View full-size slide

  43. Monitoring
    Monitoring
    45

    View full-size slide

  44. Basics
    Extensions
    Extensions
    Words Visuals
    Structure Workflow
    Extensions
    47

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  49. Sphinx, JavaScript
    Sphinx, JavaScript
    and
    and
    Beautiful Design
    Beautiful Design
    52

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  54. Practical Plan
    Practical Plan
    likely to succeed or be effective
    in real circumstances
    57

    View full-size slide

  55. Use sensible defaults
    Use sensible defaults
    58

    View full-size slide

  56. Configure
    Configure
    conf.py
    59

    View full-size slide

  57. Step by step
    Step by step
    Basics Words Visuals
    Structure Workflow
    Extensions
    60

    View full-size slide

  58. Iterate
    Iterate
    61

    View full-size slide

  59. Do your best
    Do your best
    Docs matter for your project's success.
    Get installation right.
    Automate your workflow.
    62

    View full-size slide

  60. Thank you
    Thank you
    @WillingCarol
    https://speakerdeck.com/willingc
    64

    View full-size slide