Warn when autoroles doesn't find a README.rst

This modifies autoroles to raise a warning when it finds a role
without a README.rst file.  This can be disabled with a config option
if you wish to build with warning-as-error but don't wish to document
roles.

Fix a typo in the readme for the zuul_role_paths

Add a test for the autoroles path detection by including a roles
directory under a subdir.  Manually removing the README.rst file has
validated that the warning is triggered.

Change-Id: Ia64298e6e910d21eb6f3830dd8b42e40e3444fa8
This commit is contained in:
Ian Wienand 2018-08-24 14:05:46 +10:00
parent 046c5e548c
commit a5136b73ad
5 changed files with 55 additions and 2 deletions

View File

@ -6,7 +6,13 @@ A Sphinx extension for documenting Zuul jobs.
Config options Config options
-------------- --------------
``zuul_role_path`` ``zuul_role_paths``
(str list) (str list)
List of extra paths to examine for role documentation (other than List of extra paths to examine for role documentation (other than
``roles/``) ``roles/``)
``zuul_autoroles_warn_missing``
(boolean)
Default: True
Warn when a role found with ``autoroles`` does not have a
``README.rst`` file.

View File

@ -89,3 +89,6 @@ html_logo = '_static/logo.svg'
# relative to this directory. They are copied after the builtin static files, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static'] html_static_path = ['_static']
# Sample additional role paths
zuul_role_paths = ['tests/roles']

View File

@ -10,3 +10,8 @@ Auto Project Templates
---------------------- ----------------------
.. autoproject_templates:: .. autoproject_templates::
Auto Roles
----------
.. autoroles::

View File

@ -0,0 +1,27 @@
Example README.rst
An example README.rst for a role
**Role Variables**
.. rolevar:: foo
This is a variable used by this role.
.. rolevar:: bar
:default: zero
This is a sub key.
.. rolevar:: items
:type: list
This variable is a list.
.. rolevar:: baz
This is an item in a list.
This is an (Ansible) role (Sphinx) role: :role:`example`
This is an (Ansible) role variable (Sphinx) role: :rolevar:`example.items.baz`

View File

@ -19,14 +19,19 @@ import os
from sphinx import addnodes from sphinx import addnodes
from docutils.parsers.rst import Directive from docutils.parsers.rst import Directive
from sphinx.domains import Domain, ObjType from sphinx.domains import Domain, ObjType
from sphinx.errors import SphinxError
from sphinx.roles import XRefRole from sphinx.roles import XRefRole
from sphinx.directives import ObjectDescription from sphinx.directives import ObjectDescription
from sphinx.util import logging
from sphinx.util.nodes import make_refnode from sphinx.util.nodes import make_refnode
from docutils import nodes from docutils import nodes
import yaml import yaml
logger = logging.getLogger(__name__)
class ZuulSafeLoader(yaml.SafeLoader): class ZuulSafeLoader(yaml.SafeLoader):
def __init__(self, *args, **kwargs): def __init__(self, *args, **kwargs):
@ -78,7 +83,7 @@ class ZuulDirective(Directive):
if os.path.exists(path): if os.path.exists(path):
return path return path
root = os.path.split(root)[0] root = os.path.split(root)[0]
raise Exception( raise SphinxError(
"Unable to find zuul config in zuul.yaml, .zuul.yaml," "Unable to find zuul config in zuul.yaml, .zuul.yaml,"
" zuul.d or .zuul.d") " zuul.d or .zuul.d")
@ -178,6 +183,12 @@ class ZuulDirective(Directive):
role_readme = os.path.join(d, p, 'README.rst') role_readme = os.path.join(d, p, 'README.rst')
if os.path.exists(role_readme): if os.path.exists(role_readme):
roles[p] = role_readme roles[p] = role_readme
else:
msg = "Missing role documentation: %s" % role_readme
if env.config.zuul_autoroles_warn_missing:
logger.warning(msg)
else:
logger.debug(msg)
@property @property
def zuul_role_paths(self): def zuul_role_paths(self):
@ -620,4 +631,5 @@ class ZuulDomain(Domain):
def setup(app): def setup(app):
app.add_config_value('zuul_role_paths', [], 'html') app.add_config_value('zuul_role_paths', [], 'html')
app.add_config_value('zuul_autoroles_warn_missing', True, '')
app.add_domain(ZuulDomain) app.add_domain(ZuulDomain)