qubes.dochelpers
– Helpers for Sphinx documentation¶
Documentation helpers.
This module contains classes and functions which help to maintain documentation, particularly our custom Sphinx extension.
-
class
qubes.dochelpers.
CommandCheckVisitor
(command, sub_commands, document)[source]¶ Bases:
docutils.nodes.SparseNodeVisitor
Checks if the visited sub command section nodes and the specified sub command args are in sync.
-
check_undocumented_sub_commands
()[source]¶ Call this to check if any undocumented sub_commands are left.
While the documentation talks about a ‘SparseNodeVisitor.depart_document()’ function, this function does not exists. (For details see implementation of
NodeVisitor.dispatch_departure()
) So we need to manually call this.
-
visit_Text
(node)[source]¶ If the visited text node starts with ‘alias: ‘, all the provided comma separted alias in this node, are removed from self.sub_commands
-
visit_section
(node)[source]¶ Checks if the visited sub-command section nodes exists and it options are in sync.
Uses
OptionsCheckVisitor
for checking sub-commands options
-
-
class
qubes.dochelpers.
ManpageCheckVisitor
(app, command, document)[source]¶ Bases:
docutils.nodes.SparseNodeVisitor
Checks if the sub-commands and options specified in the ‘COMMAND’ and ‘OPTIONS’ (case insensitve) sections in sync the command parser.
-
class
qubes.dochelpers.
OptionsCheckVisitor
(command, args, document)[source]¶ Bases:
docutils.nodes.SparseNodeVisitor
Checks if the visited option nodes and the specified args are in sync.
-
check_undocumented_arguments
(ignored_options=None)[source]¶ Call this to check if any undocumented arguments are left.
While the documentation talks about a ‘SparseNodeVisitor.depart_document()’ function, this function does not exists. (For details see implementation of
NodeVisitor.dispatch_departure()
) So we need to manually call this.
-
-
class
qubes.dochelpers.
VersionCheck
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶ Bases:
docutils.parsers.rst.Directive
Directive versioncheck
Check if current version (from
conf.py
) equals version specified as argument. If not, generate warning.
-
class
qubes.dochelpers.
versioncheck
(rawsource='', *children, **attributes)[source]¶ Bases:
docutils.nodes.warning
-
qubes.dochelpers.
check_man_args
(app, doctree, docname)[source]¶ Checks the manpage for undocumented or obsolete sub-commands and options.
-
qubes.dochelpers.
fetch_ticket_info
(app, number)[source]¶ Fetch info about particular trac ticket given
Parameters: - app – Sphinx app object
- number (str) – number of the ticket, without #
Return type: mapping
Raises: urllib.error.HTTPError
-
qubes.dochelpers.
ticket
(name, rawtext, text, lineno, inliner, options=None, content=None)[source]¶ Link to qubes ticket
Parameters: - name (str) – The role name used in the document
- rawtext (str) – The entire markup snippet, with role
- text (str) – The text marked with the role
- lineno (int) – The line number where rawtext appears in the input
- inliner (docutils.parsers.rst.states.Inliner) – The inliner instance that called this function
- options – Directive options for customisation
- content – The directive content for customisation