Browse Source

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
changes/48/744648/1
Ian Wienand 1 year ago
parent
commit
924ce7c7a8
  1. 3
      doc/source/conf.py
  2. 261
      zuul/sphinx/zuul.py

3
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']

261
zuul/sphinx/zuul.py

@ -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)
Loading…
Cancel
Save