From 924ce7c7a8887af5bfccc2bb9be6b79cd3b7c6f3 Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Tue, 4 Aug 2020 16:10:09 +1000 Subject: [PATCH] docs: remove zuuldocs domain In I26be542a6d4f6266f7843ada5939172656b8b847 the documentation domain was renamed to zuuldoc as a "temporary measure" :) The zuul-sphinx project now has everything required for the Zuul documentation, so we can switch the default domain to just "zuul" to use it by default and remove the unsued "zuuldocs" domain provided by zuul/sphinux/zuul.py. This means you don't need to use :zuul:... to use things from zuul-sphinx (this was rather confusing to debug, as we added :type: support to :attr: some time ago in zuul-sphinx but it wasn't being picked up, because it was using old internal versions). Change-Id: I4f7a52a2d09671f042e2d6886e7916274f3ed931 --- doc/source/conf.py | 3 +- zuul/sphinx/zuul.py | 261 -------------------------------------------- 2 files changed, 1 insertion(+), 263 deletions(-) delete mode 100644 zuul/sphinx/zuul.py diff --git a/doc/source/conf.py b/doc/source/conf.py index ba8614909c..30ae15788a 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -34,7 +34,6 @@ extensions = [ 'sphinxcontrib.openapi', 'zuul_sphinx', 'zuul.sphinx.ansible', - 'zuul.sphinx.zuul', 'reno.sphinxext', ] #extensions = ['sphinx.ext.intersphinx'] @@ -43,7 +42,7 @@ extensions = [ # The docs build references a non-local image served at zuul-ci.org. suppress_warnings = ['image.nonlocal_uri'] -primary_domain = 'zuuldoc' +primary_domain = 'zuul' # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/zuul/sphinx/zuul.py b/zuul/sphinx/zuul.py deleted file mode 100644 index 575bcb27dc..0000000000 --- a/zuul/sphinx/zuul.py +++ /dev/null @@ -1,261 +0,0 @@ -# Copyright 2017 Red Hat, Inc. -# -# Licensed under the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. You may obtain -# a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -# License for the specific language governing permissions and limitations -# under the License. - -from sphinx import addnodes -from sphinx.domains import Domain -from sphinx.roles import XRefRole -from sphinx.directives import ObjectDescription -from sphinx.util.nodes import make_refnode -from docutils import nodes - -from typing import Dict # noqa - - -class ZuulConfigObject(ObjectDescription): - object_names = { - 'attr': 'attribute', - 'var': 'variable', - } - - def get_path(self): - return self.env.ref_context.get('zuuldoc:attr_path', []) - - def get_display_path(self): - return self.env.ref_context.get('zuuldoc:display_attr_path', []) - - @property - def parent_pathname(self): - return '.'.join(self.get_display_path()) - - @property - def full_pathname(self): - name = self.names[-1].lower() - return '.'.join(self.get_path() + [name]) - - def add_target_and_index(self, name, sig, signode): - targetname = self.objtype + '-' + self.full_pathname - if targetname not in self.state.document.ids: - signode['names'].append(targetname) - signode['ids'].append(targetname) - signode['first'] = (not self.names) - self.state.document.note_explicit_target(signode) - objects = self.env.domaindata['zuuldoc']['objects'] - if targetname in objects: - self.state_machine.reporter.warning( - 'duplicate object description of %s, ' % targetname + - 'other instance in ' + - self.env.doc2path(objects[targetname][0]) + - ', use :noindex: for one of them', - line=self.lineno) - objects[targetname] = (self.env.docname, self.objtype) - - objname = self.object_names.get(self.objtype, self.objtype) - if self.parent_pathname: - indextext = '%s (%s of %s)' % (name, objname, - self.parent_pathname) - else: - indextext = '%s (%s)' % (name, objname) - self.indexnode['entries'].append(('single', indextext, - targetname, '', None)) - - -class ZuulAttrDirective(ZuulConfigObject): - has_content = True - - option_spec = { - 'required': lambda x: x, - 'default': lambda x: x, - 'noindex': lambda x: x, - } - - def before_content(self): - path = self.env.ref_context.setdefault('zuuldoc:attr_path', []) - path.append(self.names[-1]) - path = self.env.ref_context.setdefault('zuuldoc:display_attr_path', []) - path.append(self.names[-1]) - - def after_content(self): - path = self.env.ref_context.get('zuuldoc:attr_path') - if path: - path.pop() - path = self.env.ref_context.get('zuuldoc:display_attr_path') - if path: - path.pop() - - def handle_signature(self, sig, signode): - path = self.get_display_path() - signode['is_multiline'] = True - line = addnodes.desc_signature_line() - line['add_permalink'] = True - for x in path: - line += addnodes.desc_addname(x + '.', x + '.') - line += addnodes.desc_name(sig, sig) - if 'required' in self.options: - line += addnodes.desc_annotation(' (required)', ' (required)') - signode += line - if 'default' in self.options: - line = addnodes.desc_signature_line() - line += addnodes.desc_type('Default: ', 'Default: ') - line += nodes.literal(self.options['default'], - self.options['default']) - signode += line - return sig - - -class ZuulValueDirective(ZuulConfigObject): - has_content = True - - def handle_signature(self, sig, signode): - signode += addnodes.desc_name(sig, sig) - return sig - - -class ZuulVarDirective(ZuulConfigObject): - has_content = True - - option_spec = { - 'type': lambda x: x, - 'hidden': lambda x: x, - 'noindex': lambda x: x, - } - - type_map = { - 'list': '[]', - 'dict': '{}', - } - - def get_type_str(self): - if 'type' in self.options: - return self.type_map[self.options['type']] - return '' - - def before_content(self): - path = self.env.ref_context.setdefault('zuuldoc:attr_path', []) - element = self.names[-1] - path.append(element) - path = self.env.ref_context.setdefault('zuuldoc:display_attr_path', []) - element = self.names[-1] + self.get_type_str() - path.append(element) - - def after_content(self): - path = self.env.ref_context.get('zuuldoc:attr_path') - if path: - path.pop() - path = self.env.ref_context.get('zuuldoc:display_attr_path') - if path: - path.pop() - - def handle_signature(self, sig, signode): - if 'hidden' in self.options: - return sig - path = self.get_display_path() - for x in path: - signode += addnodes.desc_addname(x + '.', x + '.') - signode += addnodes.desc_name(sig, sig) - return sig - - -class ZuulStatDirective(ZuulConfigObject): - has_content = True - - option_spec = { - 'type': lambda x: x, - 'hidden': lambda x: x, - 'noindex': lambda x: x, - } - - def before_content(self): - path = self.env.ref_context.setdefault('zuuldoc:attr_path', []) - element = self.names[-1] - path.append(element) - path = self.env.ref_context.setdefault('zuuldoc:display_attr_path', []) - element = self.names[-1] - path.append(element) - - def after_content(self): - path = self.env.ref_context.get('zuuldoc:attr_path') - if path: - path.pop() - path = self.env.ref_context.get('zuuldoc:display_attr_path') - if path: - path.pop() - - def handle_signature(self, sig, signode): - if 'hidden' in self.options: - return sig - path = self.get_display_path() - for x in path: - signode += addnodes.desc_addname(x + '.', x + '.') - signode += addnodes.desc_name(sig, sig) - if 'type' in self.options: - t = ' (%s)' % self.options['type'] - signode += addnodes.desc_annotation(t, t) - return sig - - -class ZuulAbbreviatedXRefRole(XRefRole): - - def process_link(self, env, refnode, has_explicit_title, title, - target): - title, target = super(ZuulAbbreviatedXRefRole, self).process_link( - env, refnode, has_explicit_title, title, target) - if not has_explicit_title: - title = title.split('.')[-1] - return title, target - - -class ZuulDomain(Domain): - name = 'zuuldoc' - label = 'Zuul' - - directives = { - 'attr': ZuulAttrDirective, - 'value': ZuulValueDirective, - 'var': ZuulVarDirective, - 'stat': ZuulStatDirective, - } - - roles = { - 'attr': XRefRole(innernodeclass=nodes.inline, # type: ignore - warn_dangling=True), - 'value': ZuulAbbreviatedXRefRole( - innernodeclass=nodes.inline, # type: ignore - warn_dangling=True), - 'var': XRefRole(innernodeclass=nodes.inline, # type: ignore - warn_dangling=True), - 'stat': XRefRole(innernodeclass=nodes.inline, # type: ignore - warn_dangling=True), - } - - initial_data = { - 'objects': {}, - } # type: Dict[str, Dict] - - def resolve_xref(self, env, fromdocname, builder, type, target, - node, contnode): - objects = self.data['objects'] - name = type + '-' + target - obj = objects.get(name) - if obj: - return make_refnode(builder, fromdocname, obj[0], name, - contnode, name) - - def clear_doc(self, docname): - for fullname, (fn, _l) in list(self.data['objects'].items()): - if fn == docname: - del self.data['objects'][fullname] - - -def setup(app): - app.add_domain(ZuulDomain)