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
   

   View 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 Slide

3. Challenges
   Challenges
   3
   

   View Slide

4. People
   People
   Opinions
   4
   

   View Slide

5. Tools
   Tools
   Scalpel
   Sledgehammer
   Sphinx
   ???
   5
   

   View Slide

6. Processes
   Processes
   Reduce
   Reuse
   Recycle
   6
   

   View Slide

7. Time
   Time
   Efficiency
   7
   

   View Slide

8. View Slide

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

   View Slide

10. Get practical
    Get practical
    10
    

    View Slide

11. Why
    Why
    11
    

    View Slide

12. Roadmap
    Roadmap
    12
    

    View Slide

13. Basics
    Basics
    Basics
    13
    

    View Slide

14. python3 ­m pip install Sphinx
    Install
    Install
    14
    

    View Slide

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

    View Slide

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

    View Slide

17. conf.py
    settings
    execute code
    17
    

    View Slide

18. make clean
    make build
    Build
    Build
    18
    

    View Slide

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

    View Slide

20. Basics
    Words
    Words
    Words
    20
    

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

30. Basics
    Visuals
    Visuals
    Words Visuals
    30
    

    View Slide

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
    

    View Slide

32. image
    image
    (rendered)
    (rendered)
    32
    

    View Slide

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
    

    View Slide

34. directives
    directives
    (rendered)
    (rendered)
    34
    

    View Slide

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
    

    View Slide

36. code
    code
    (rendered)
    36
    

    View Slide

37. Basics
    Structure
    Structure
    Words Visuals
    Structure
    37
    

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

41. Basics
    Workflow
    Workflow
    Words Visuals
    Structure Workflow
    41
    

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

45. Monitoring
    Monitoring
    45
    

    View Slide

46. View Slide

47. Basics
    Extensions
    Extensions
    Words Visuals
    Structure Workflow
    Extensions
    47
    

    View Slide

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
    

    View Slide

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

    View Slide

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
    

    View Slide

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
    

    View Slide

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

    View Slide

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
    

    View Slide

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
    

    View Slide

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

    View Slide

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
    

    View Slide

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

    View Slide

58. Use sensible defaults
    Use sensible defaults
    58
    

    View Slide

59. Configure
    Configure
    conf.py
    59
    

    View Slide

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

    View Slide

61. Iterate
    Iterate
    61
    

    View Slide

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

    View Slide

63. View Slide

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

    View Slide