Support building docs

config/README.rst

@@ -116,6 +116,14 @@ The following arguments are supported.
 --with-pypy
   Enable PyPy support. (Only needed one time as it is stored in .meta.cfg.)
 
+--with-docs
+  Enable building the documentation using sphinx. (Only needed one time as it
+  is stored in .meta.cfg.)
+
+--with-sphinx-doctests
+  Enable running the documentation as doctest using sphinx. (Only needed one
+  time as it is stored in .meta.cfg.)
+
 Options
 +++++++
 
@@ -132,6 +140,8 @@ updated. Example:
     commit-id = < commit-hash >
     fail-under = 98
     with-pypy = False
+    with-docs = True
+    with-sphinx-doctests = False
     additional-manifest-rules =
 
 
@@ -152,6 +162,12 @@ fail-under
 with-pypy
   Does the package support PyPy: True/False
 
+with-docs
+  Build the documentation via sphinx: True/False
+
+with-sphinx-doctests
+  Run the documentation as doctest using sphinx: True/False
+
 additional-manifest-rules
   Additional rules to be added at the end of the MANIFEST.in file.
 

config/buildout-recipe/setup.cfg

@@ -10,3 +10,5 @@ builtins = write, system, cat, join
 ignore =
     .editorconfig
     .meta.cfg
+    docs/_build/html/_sources/*
+    docs/_build/doctest/*

config/buildout-recipe/tox.ini.jj2

@@ -10,6 +10,9 @@ envlist =
 {% if with_pypy %}
     pypy,
     pypy3,
+{% endif %}
+{% if with_docs %}
+    docs,
 {% endif %}
     coverage
 
@@ -19,7 +22,14 @@ deps =
     zope.testrunner
 commands =
     zope-testrunner --test-path=src []
-extras = test
+{% if with_sphinx_doctests %}
+    sphinx-build -b doctest -d {envdir}/.cache/doctrees docs {envdir}/.cache/doctest
+{% endif %}
+extras =
+    test
+{% if with_sphinx_doctests %}
+    docs
+{% endif %}
 
 [testenv:lint]
 basepython = python3
@@ -33,6 +43,20 @@ commands =
     check-manifest
     check-python-versions
 
+{% if with_docs %}
+[testenv:docs]
+basepython = python3
+{% if not with_sphinx_doctests %}
+extras =
+    docs
+{% endif %}
+commands =
+    sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html
+{% if with_sphinx_doctests %}
+    sphinx-build -b doctest -d docs/_build/doctrees docs docs/_build/doctest
+{% endif %}
+
+{% endif %}
 [testenv:coverage]
 basepython = python3
 setenv =
@@ -44,6 +68,9 @@ deps =
 commands =
     coverage erase
     coverage run -m zope.testrunner --test-path=src []
+{% if with_sphinx_doctests %}
+    coverage run -a -m sphinx -b doctest -d {envdir}/.cache/doctrees docs {envdir}/.cache/doctest
+{% endif %}
     coverage combine
     coverage html
     coverage report -m --fail-under=%(fail_under)s

config/config-package.py

@@ -55,6 +55,19 @@ def copy_with_meta(template_name, destination, config_type, **kw):
     action='store_true',
     default=False,
     help='Activate PyPy support if not already configured in .meta.cfg.')
+parser.add_argument(
+    '--with-docs',
+    dest='with_docs',
+    action='store_true',
+    default=False,
+    help='Activate building docs if not already configured in .meta.cfg.')
+parser.add_argument(
+    '--with-sphinx-doctests',
+    dest='with_sphinx_doctests',
+    action='store_true',
+    default=False,
+    help='Activate running doctests with sphinx if not already configured in'
+         ' .meta.cfg.')
 parser.add_argument(
     'type',
      choices=[
@@ -105,6 +118,11 @@ def copy_with_meta(template_name, destination, config_type, **kw):
     'git', 'log', '-n1', '--format=format:%H', capture_output=True).stdout
 with_pypy = meta_opts.getboolean('with-pypy', False) or args.with_pypy
 meta_opts['with-pypy'] = str(with_pypy)
+with_docs = meta_opts.getboolean('with-docs', False) or args.with_docs
+meta_opts['with-docs'] = str(with_docs)
+with_sphinx_doctests = meta_opts.getboolean(
+    'with-sphinx-doctests', False) or args.with_sphinx_doctests
+meta_opts['with-sphinx-doctests'] = str(with_sphinx_doctests)
 
 # Copy template files
 copy_with_meta('setup.cfg', path / 'setup.cfg', config_type)
@@ -127,10 +145,11 @@ def copy_with_meta(template_name, destination, config_type, **kw):
 fail_under = meta_opts.setdefault('fail-under', '0')
 copy_with_meta(
     'tox.ini.jj2', path / 'tox.ini', config_type,
-    fail_under=fail_under, with_pypy=with_pypy)
+    fail_under=fail_under, with_pypy=with_pypy,
+    with_docs=with_docs, with_sphinx_doctests=with_sphinx_doctests)
 copy_with_meta(
     'tests.yml.jj2', workflows / 'tests.yml', config_type,
-    with_pypy=with_pypy)
+    with_pypy=with_pypy, with_docs=with_docs)
 
 
 # Modify MANIFEST.in with meta options

config/default/tests.yml.jj2

@@ -23,6 +23,9 @@ jobs:
 {% if with_pypy %}
         - ["pypy2", "pypy"]
         - ["pypy3", "pypy3"]
+{% endif %}
+{% if with_docs %}
+        - ["3.8",   "docs"]
 {% endif %}
         - ["3.8",   "coverage"]
 

config/pure-python/setup.cfg

@@ -8,3 +8,5 @@ doctests = 1
 ignore =
     .editorconfig
     .meta.cfg
+    docs/_build/html/_sources/*
+    docs/_build/doctest/*

config/pure-python/tox.ini.jj2

@@ -10,6 +10,9 @@ envlist =
 {% if with_pypy %}
     pypy,
     pypy3,
+{% endif %}
+{% if with_docs %}
+    docs,
 {% endif %}
     coverage
 
@@ -19,7 +22,14 @@ deps =
     zope.testrunner
 commands =
     zope-testrunner --test-path=src []
-extras = test
+{% if with_sphinx_doctests %}
+    sphinx-build -b doctest -d {envdir}/.cache/doctrees docs {envdir}/.cache/doctest
+{% endif %}
+extras =
+    test
+{% if with_sphinx_doctests %}
+    docs
+{% endif %}
 
 [testenv:lint]
 basepython = python3
@@ -33,6 +43,20 @@ commands =
     check-manifest
     check-python-versions
 
+{% if with_docs %}
+[testenv:docs]
+basepython = python3
+{% if not with_sphinx_doctests %}
+extras =
+    docs
+{% endif %}
+commands =
+    sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html
+{% if with_sphinx_doctests %}
+    sphinx-build -b doctest -d docs/_build/doctrees docs docs/_build/doctest
+{% endif %}
+
+{% endif %}
 [testenv:coverage]
 basepython = python3
 deps =
@@ -41,6 +65,9 @@ deps =
     zope.testrunner
 commands =
     coverage run -m zope.testrunner --test-path=src []
+{% if with_sphinx_doctests %}
+    coverage run -a -m sphinx -b doctest -d {envdir}/.cache/doctrees docs {envdir}/.cache/doctest
+{% endif %}
     coverage html
     coverage report -m --fail-under=%(fail_under)s