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:

import pathlib
import sys
from datetime import datetime

import sphinx_rtd_theme

import caproto
import caproto.docs

module_path = pathlib.Path(__file__).resolve().parents[2]
sys.path.insert(0, str(module_path))


project = 'YOUR_PROJECT'
author = 'YOUR_NAME'

copyright = f'{datetime.now().year}, {author}'

# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = ''

# -- General configuration ---------------------------------------------------
needs_sphinx = '3.2.1'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'sphinx.ext.intersphinx',
    'numpydoc',
    # 'docs_versions_menu',
    'sphinx_rtd_theme',
]

templates_path = [caproto.docs.templates.PATH]

source_suffix = '.rst'
master_doc = 'index'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
language = 'python'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = []

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# -- Options for HTML output -------------------------------------------------
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

# html_theme_options = {}
html_static_path = ['_static']

# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
# html_sidebars = {}

# -- Options for HTMLHelp output ---------------------------------------------
htmlhelp_basename = 'YOUR_PROJECT'

# -- Extension configuration -------------------------------------------------
autodoc_default_options = {
    'members': '',
    'member-order': 'bysource',
    'special-members': '',
    'undoc-members': False,
    'exclude-members': ''
}

intersphinx_mapping = {
    # 'ophyd': ('https://blueskyproject.io/ophyd', None),
    'python': ('https://docs.python.org/3', None),
    # 'numpy': ('https://docs.scipy.org/doc/numpy', None),
    'caproto': ('https://caproto.github.io/caproto/master', None),
}

autosummary_generate = True

# Duplicate attributes will be generated without this:
autoclass_content = 'init'

# Tons of warnings will be emitted without this:
numpydoc_show_class_members = False
autosummary_context = {
    **caproto.docs.autosummary_context,
    # The default assumes your repository root is one level up from conf.py.
    # If that is not accurate, uncomment and modify the following line:
    # 'project_root': '..',
}
html_context = {
    **autosummary_context,
    # 'css_files': [
    #     '_static/theme_overrides.css',  # override wide tables in RTD theme
    # ],
}


def setup(app):
    # Add your own setup here
    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

---------
PV Groups
---------

.. currentmodule:: package

.. autosummary::
    :toctree: ioc

   pkg.MyGroup


--------
Full API
--------

.. autosummary::
    :toctree: ioc

    pkg