Writing Your Own Documentation

caproto provides some Sphinx and autodoc/autosummary-based helpers to aid users in the creation of their own (PVGroup-based) IOC documentation.

Sample conf.py

An HTML-centric conf.py may look like the following:

  1import pathlib
  2import sys
  3from datetime import datetime
  4
  5import sphinx_rtd_theme
  6
  7import caproto
  8import caproto.docs
  9
 10module_path = pathlib.Path(__file__).resolve().parents[2]
 11sys.path.insert(0, str(module_path))
 12
 13
 14project = 'YOUR_PROJECT'
 15author = 'YOUR_NAME'
 16
 17copyright = f'{datetime.now().year}, {author}'
 18
 19# The short X.Y version
 20version = ''
 21# The full version, including alpha/beta/rc tags
 22release = ''
 23
 24# -- General configuration ---------------------------------------------------
 25needs_sphinx = '3.2.1'
 26
 27extensions = [
 28    'sphinx.ext.autodoc',
 29    'sphinx.ext.autosummary',
 30    'sphinx.ext.todo',
 31    'sphinx.ext.coverage',
 32    'sphinx.ext.mathjax',
 33    'sphinx.ext.viewcode',
 34    'sphinx.ext.githubpages',
 35    'sphinx.ext.intersphinx',
 36    'numpydoc',
 37    # 'docs_versions_menu',
 38    'sphinx_rtd_theme',
 39]
 40
 41templates_path = [caproto.docs.templates.PATH]
 42
 43source_suffix = '.rst'
 44master_doc = 'index'
 45
 46# The language for content autogenerated by Sphinx. Refer to documentation
 47# for a list of supported languages.
 48language = 'python'
 49
 50# List of patterns, relative to source directory, that match files and
 51# directories to ignore when looking for source files.
 52# This pattern also affects html_static_path and html_extra_path .
 53exclude_patterns = []
 54
 55# The name of the Pygments (syntax highlighting) style to use.
 56pygments_style = 'sphinx'
 57
 58# -- Options for HTML output -------------------------------------------------
 59html_theme = 'sphinx_rtd_theme'
 60html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 61
 62# html_theme_options = {}
 63html_static_path = ['_static']
 64
 65# Custom sidebar templates, must be a dictionary that maps document names
 66# to template names.
 67# html_sidebars = {}
 68
 69# -- Options for HTMLHelp output ---------------------------------------------
 70htmlhelp_basename = 'YOUR_PROJECT'
 71
 72# -- Extension configuration -------------------------------------------------
 73autodoc_default_options = {
 74    'members': '',
 75    'member-order': 'bysource',
 76    'special-members': '',
 77    'undoc-members': False,
 78    'exclude-members': ''
 79}
 80
 81intersphinx_mapping = {
 82    # 'ophyd': ('https://blueskyproject.io/ophyd', None),
 83    'python': ('https://docs.python.org/3', None),
 84    # 'numpy': ('https://docs.scipy.org/doc/numpy', None),
 85    'caproto': ('https://caproto.github.io/caproto/master', None),
 86}
 87
 88autosummary_generate = True
 89
 90# Duplicate attributes will be generated without this:
 91autoclass_content = 'init'
 92
 93# Tons of warnings will be emitted without this:
 94numpydoc_show_class_members = False
 95autosummary_context = {
 96    **caproto.docs.autosummary_context,
 97    # The default assumes your repository root is one level up from conf.py.
 98    # If that is not accurate, uncomment and modify the following line:
 99    # 'project_root': '..',
100}
101html_context = {
102    **autosummary_context,
103    # 'css_files': [
104    #     '_static/theme_overrides.css',  # override wide tables in RTD theme
105    # ],
106}
107
108
109def setup(app):
110    # Add your own setup here
111    caproto.docs.setup(app)

Any and all of this can be customized. Users may also copy the templates out of caproto, though any improvements to these templates are always welcome in caproto itself.

Sample requirements-docs.txt

Building your documentation will require extra dependencies that aren’t necessary to run your package, most likely. The caproto developers recommend creating a separate requirements file that can be installed by way of pip or conda (i.e., pip install --requirement requirements-docs.txt or conda install --file requirements-docs.txt).

docs-versions-menu
numpydoc
sphinx>=3.2.1
sphinx_rtd_theme>=0.5.0

docs-versions-menu is useful for building versioned documentation targeting GitHub pages using continuous integration. It is unnecessary if you will only be building documentation locally or only care about the latest release documentation.

Using autosummary

 1---------
 2PV Groups
 3---------
 4
 5.. currentmodule:: package
 6
 7.. autosummary::
 8    :toctree: ioc
 9
10   pkg.MyGroup
11
12
13--------
14Full API
15--------
16
17.. autosummary::
18    :toctree: ioc
19
20    pkg