diff --git a/config/README.rst b/config/README.rst index 3b8b8f4..b156e96 100644 --- a/config/README.rst +++ b/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. diff --git a/config/buildout-recipe/setup.cfg b/config/buildout-recipe/setup.cfg index 45fe899..ad7ed17 100644 --- a/config/buildout-recipe/setup.cfg +++ b/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/* diff --git a/config/buildout-recipe/tox.ini.j2 b/config/buildout-recipe/tox.ini.j2 index 69a8129..34b5ed5 100644 --- a/config/buildout-recipe/tox.ini.j2 +++ b/config/buildout-recipe/tox.ini.j2 @@ -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 diff --git a/config/config-package.py b/config/config-package.py index 7e3e1de..d0bb8dc 100755 --- a/config/config-package.py +++ b/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.j2', 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.j2', workflows / 'tests.yml', config_type, - with_pypy=with_pypy) + with_pypy=with_pypy, with_docs=with_docs) # Modify MANIFEST.in with meta options diff --git a/config/default/tests.yml.j2 b/config/default/tests.yml.j2 index 46dc3a1..5d0e378 100644 --- a/config/default/tests.yml.j2 +++ b/config/default/tests.yml.j2 @@ -23,6 +23,9 @@ jobs: {% if with_pypy %} - ["pypy2", "pypy"] - ["pypy3", "pypy3"] +{% endif %} +{% if with_docs %} + - ["3.8", "docs"] {% endif %} - ["3.8", "coverage"] diff --git a/config/pure-python/setup.cfg b/config/pure-python/setup.cfg index 6bff33f..4c17add 100644 --- a/config/pure-python/setup.cfg +++ b/config/pure-python/setup.cfg @@ -8,3 +8,5 @@ doctests = 1 ignore = .editorconfig .meta.cfg + docs/_build/html/_sources/* + docs/_build/doctest/* diff --git a/config/pure-python/tox.ini.j2 b/config/pure-python/tox.ini.j2 index 8a4b79b..234453e 100644 --- a/config/pure-python/tox.ini.j2 +++ b/config/pure-python/tox.ini.j2 @@ -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