summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorIan Wienand <iwienand@redhat.com>2018-09-25 16:43:44 +1000
committerIan Wienand <iwienand@redhat.com>2018-09-28 20:18:28 +1000
commit5bc7086580b67d5f5a3163a1ca62dba6169344a7 (patch)
tree0ed84bae315b17834b969846533e4624f61d85e2
parent0210c9df03d0c2098a2ff7024f491afdc36ca071 (diff)
Add attr-overview directive0.3.0
This directive creates a bullet-point list of all the attributes defined within a file. The idea is to give a quick overview reference for config file options. There are two options to start with -- maxdepth is similar to the TOC option and only shows certain levels of options; prefix allows to filter down to a smaller set of options if required. I've reworked the documentation examples as part of testing this. The various components are moved into separate files. On the main page, moved the config options into the main documentation (and use the zuul attributes :) and pointed out that you can view the source of each sample page to see how to generate what you see. Change-Id: I6b0f414f50428c6e04b3aeb2a2c1f9196de80ce6
Notes
Notes (review): Code-Review+2: James E. Blair <corvus@inaugust.com> Code-Review+2: Tobias Henkel <tobias.henkel@bmw.de> Workflow+1: Tobias Henkel <tobias.henkel@bmw.de> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Fri, 12 Oct 2018 04:16:24 +0000 Reviewed-on: https://review.openstack.org/604980 Project: openstack-infra/zuul-sphinx Branch: refs/heads/master
-rw-r--r--README.rst16
-rw-r--r--doc/source/example-attributes.rst61
-rw-r--r--doc/source/example-jobs.rst5
-rw-r--r--doc/source/example-roles.rst5
-rw-r--r--doc/source/example-statistics.rst13
-rw-r--r--doc/source/example-templates.rst5
-rw-r--r--doc/source/example-variables.rst25
-rw-r--r--doc/source/examples.rst71
-rw-r--r--doc/source/index.rst40
-rw-r--r--zuul_sphinx/zuul.py99
10 files changed, 241 insertions, 99 deletions
diff --git a/README.rst b/README.rst
index 7b17f13..3dcb790 100644
--- a/README.rst
+++ b/README.rst
@@ -1,18 +1,6 @@
1Zuul Sphinx 1Zuul Sphinx
2=========== 2===========
3 3
4A Sphinx extension for documenting Zuul jobs. 4A `Sphinx <https://www.sphinx-doc.org>`__ extension for documenting
5`Zuul <https://zuul-ci.org>`__ jobs and configuration.
5 6
6Config options
7--------------
8
9``zuul_role_paths``
10 (str list)
11 List of extra paths to examine for role documentation (other than
12 ``roles/``)
13
14``zuul_autoroles_warn_missing``
15 (boolean)
16 Default: True
17 Warn when a role found with ``autoroles`` does not have a
18 ``README.rst`` file.
diff --git a/doc/source/example-attributes.rst b/doc/source/example-attributes.rst
new file mode 100644
index 0000000..49cf6da
--- /dev/null
+++ b/doc/source/example-attributes.rst
@@ -0,0 +1,61 @@
1Configuration Attributes
2------------------------
3
4.. attr:: example-attr
5 :required:
6
7 This is an example configuration attribute.
8
9 .. attr:: foo
10 :default: bar
11 :example: sample_value_for_example_attr
12 :type: str
13
14 A sub attribute.
15
16 .. value:: bar
17
18 An attribute value.
19
20 .. value:: baz
21
22 Another attribute value.
23
24 .. attr:: moo
25
26 An even further nested attribute
27
28 .. attr:: boo
29
30 And one more for good luck
31
32.. attr:: another-example-attr
33
34 And back to the top level
35
36References
37==========
38
39This is an attribute role: :attr:`example-attr.foo`
40
41This is an attribute value role: :value:`example-attr.foo.bar`
42
43Summaries
44=========
45
46All attributes
47^^^^^^^^^^^^^^
48
49.. attr-overview::
50
51Only one level
52^^^^^^^^^^^^^^
53
54.. attr-overview::
55 :maxdepth: 1
56
57Only example-attr.foo prefix
58^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59
60.. attr-overview::
61 :prefix: example-attr.foo
diff --git a/doc/source/example-jobs.rst b/doc/source/example-jobs.rst
index 26dfff8..39c437c 100644
--- a/doc/source/example-jobs.rst
+++ b/doc/source/example-jobs.rst
@@ -1,8 +1,5 @@
1Example Jobs
2============
3
4Jobs 1Jobs
5---- 2====
6 3
7.. job:: example 4.. job:: example
8 5
diff --git a/doc/source/example-roles.rst b/doc/source/example-roles.rst
index 827bef0..b32022e 100644
--- a/doc/source/example-roles.rst
+++ b/doc/source/example-roles.rst
@@ -1,8 +1,5 @@
1Example Roles
2=============
3
4Roles 1Roles
5----- 2=====
6 3
7.. role:: example 4.. role:: example
8 5
diff --git a/doc/source/example-statistics.rst b/doc/source/example-statistics.rst
new file mode 100644
index 0000000..f4153c3
--- /dev/null
+++ b/doc/source/example-statistics.rst
@@ -0,0 +1,13 @@
1Statistics
2----------
3
4.. stat:: example-stat
5
6 This is an example statistic.
7
8 .. stat:: foo
9 :type: counter
10
11 A sub stat.
12
13This is a statistics role: :stat:`example-stat.foo`
diff --git a/doc/source/example-templates.rst b/doc/source/example-templates.rst
index 62bc452..dfe0ced 100644
--- a/doc/source/example-templates.rst
+++ b/doc/source/example-templates.rst
@@ -1,8 +1,5 @@
1Example Project Templates
2=========================
3
4Project Templates 1Project Templates
5----------------- 2=================
6 3
7.. project_template:: example 4.. project_template:: example
8 5
diff --git a/doc/source/example-variables.rst b/doc/source/example-variables.rst
new file mode 100644
index 0000000..39efe07
--- /dev/null
+++ b/doc/source/example-variables.rst
@@ -0,0 +1,25 @@
1Variables
2---------
3
4.. var:: example-variable
5
6 This is an example variable.
7
8 .. var:: foo
9
10 This is a variable.
11
12 .. var:: bar
13
14 This is a sub key.
15
16 .. var:: items
17 :type: list
18
19 This variable is a list.
20
21 .. var:: baz
22
23 This is an item in a list.
24
25This is a variable role: :var:`example-variable.items.baz`
diff --git a/doc/source/examples.rst b/doc/source/examples.rst
deleted file mode 100644
index 3986fd8..0000000
--- a/doc/source/examples.rst
+++ /dev/null
@@ -1,71 +0,0 @@
1Examples
2========
3
4Configuration Attributes
5------------------------
6
7.. attr:: example-attr
8 :required:
9
10 This is an example configuration attribute.
11
12 .. attr:: foo
13 :default: bar
14 :example: sample_value_for_example_attr
15 :type: str
16
17 A sub attribute.
18
19 .. value:: bar
20
21 An attribute value.
22
23 .. value:: baz
24
25 Another attribute value.
26
27This is an attribute role: :attr:`example-attr.foo`
28
29This is an attribute value role: :value:`example-attr.foo.bar`
30
31
32Job Variables
33-------------
34
35.. var:: example-variable
36
37 This is an example variable.
38
39 .. var:: foo
40
41 This is a variable.
42
43 .. var:: bar
44
45 This is a sub key.
46
47 .. var:: items
48 :type: list
49
50 This variable is a list.
51
52 .. var:: baz
53
54 This is an item in a list.
55
56This is a variable role: :var:`example-variable.items.baz`
57
58
59Statistics
60----------
61
62.. stat:: example-stat
63
64 This is an example statistic.
65
66 .. stat:: foo
67 :type: counter
68
69 A sub stat.
70
71This is a statistics role: :stat:`example-stat.foo`
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 2c950d9..41799db 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,16 +1,52 @@
1.. include:: ../../README.rst 1.. include:: ../../README.rst
2 2
3Overview
4--------
5
6This documentation has full examples of how to use the zuul-sphinx
7features.
8
9Config options
10--------------
11
12The following options can be set
13
14.. attr:: zuul_role_paths
15 :type: str list
16
17 List of extra paths to examine for role documentation (other than
18 ``roles/``)
19
20.. attr:: zuul_roles_warn_missing
21 :type: bool
22 :default: True
23
24 Warn when a role found with ``autoroles`` does not have a
25 ``README.rst`` file.
26
27
28Examples
29--------
30
31.. note::
32
33 To see the commands that produces the rendered output for this page
34 or any of the examples below, use the ``Show Source`` link at the
35 bottom of the page.
36
3.. toctree:: 37.. toctree::
4 :maxdepth: 2 38 :maxdepth: 2
5 39
6 examples 40 example-variables
41 example-attributes
7 example-jobs 42 example-jobs
8 example-templates 43 example-templates
9 example-roles 44 example-roles
10 example-autodoc 45 example-autodoc
46 example-statistics
11 47
12Indices and tables 48Indices and tables
13================== 49------------------
14 50
15* :ref:`genindex` 51* :ref:`genindex`
16* :ref:`search` 52* :ref:`search`
diff --git a/zuul_sphinx/zuul.py b/zuul_sphinx/zuul.py
index a2e6381..37a6bd3 100644
--- a/zuul_sphinx/zuul.py
+++ b/zuul_sphinx/zuul.py
@@ -17,7 +17,9 @@ import codecs
17import os 17import os
18 18
19from sphinx import addnodes 19from sphinx import addnodes
20from docutils import nodes
20from docutils.parsers.rst import Directive 21from docutils.parsers.rst import Directive
22from docutils.parsers.rst import directives
21from sphinx.domains import Domain, ObjType 23from sphinx.domains import Domain, ObjType
22from sphinx.errors import SphinxError 24from sphinx.errors import SphinxError
23from sphinx.roles import XRefRole 25from sphinx.roles import XRefRole
@@ -649,7 +651,104 @@ class ZuulDomain(Domain):
649 del self.data['objects'][fullname] 651 del self.data['objects'][fullname]
650 652
651 653
654######################################################################
655#
656# Attribute overview directives
657#
658
659# TODO(ianw)
660#
661# There are many ways this could be improved
662# * fancy indentation of nested attrs in the overview
663# * (related) stripping of prefixes for nesting
664# * something better than a bullet list (table?)
665# * add something to attributes so that they can list thier child
666# attributes atuomatically. Something like
667#
668# .. attr:: foo
669# :show_overview:
670#
671# This is the foo option
672#
673# and then
674#
675# .. attr-overview::
676# :maxdepth: 1
677# :prefix: foo
678#
679# gets automatically inserted for you, and then you should have a
680# sensible overview of the sub-options of "foo" inside the
681# top-level "foo" documentation
682# * figure out if it could be added to TOC
683
684class attroverview(nodes.General, nodes.Element):
685 pass
686
687class AttrOverviewDirective(Directive):
688 option_arguments = 2
689 option_spec = {
690 'maxdepth': directives.positive_int,
691 'prefix': directives.unchanged
692 }
693
694 def run(self):
695 attr = attroverview('')
696 if 'maxdepth' in self.options:
697 attr._maxdepth = self.options['maxdepth']
698 if 'prefix' in self.options:
699 attr._prefix = self.options['prefix']
700 return [attr]
701
702
703def process_attr_overview(app, doctree, fromdocname):
704 objects = app.builder.env.domaindata['zuul']['objects']
705
706 for node in doctree.traverse(attroverview):
707 content = []
708
709 l = nodes.bullet_list()
710 content.append(l)
711 # The "..attr" calls have built up this dictionary, of the format
712 #
713 # {
714 # attr-foo : (docname, attr),
715 # attr-foo.bar : (docname, attr),
716 # }
717 #
718 # So, in words, we look at all items in this list that have
719 # our docname and the attr "type" (second argument) and build
720 # them into a bullet list.
721 for k,v in objects.items():
722 if v[0] == fromdocname and v[1] == 'attr':
723 # remove the leading "attr-" for the link name ... the
724 # whole thing is is the refid however.
725 name = k[5:]
726
727 # e.g. if we have foo.bar.baz that's considered 3
728 # levels
729 if getattr(node, '_maxdepth', None):
730 maxdepth = node._maxdepth
731 if len(name.split('.')) > maxdepth:
732 continue
733
734 if getattr(node, '_prefix', None):
735 prefix = node._prefix
736 if not name.startswith(prefix.strip()):
737 continue
738
739 item = nodes.list_item()
740 para = nodes.paragraph()
741 refnode = nodes.reference(name, name, internal=True, refid=k)
742 para.append(refnode)
743 item.append(para)
744 l.append(item)
745
746 node.replace_self(content)
747
748
652def setup(app): 749def setup(app):
653 app.add_config_value('zuul_role_paths', [], 'html') 750 app.add_config_value('zuul_role_paths', [], 'html')
654 app.add_config_value('zuul_autoroles_warn_missing', True, '') 751 app.add_config_value('zuul_autoroles_warn_missing', True, '')
752 app.add_directive('attr-overview', AttrOverviewDirective)
753 app.connect('doctree-resolved', process_attr_overview)
655 app.add_domain(ZuulDomain) 754 app.add_domain(ZuulDomain)