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)

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()

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)

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)

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)

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.

visit_section(node)

If section title is OPTIONS or COMMANDS dispatch the apropriate NodeVisitor.

class qubes.dochelpers.OptionsCheckVisitor(command, args, document)

Bases: docutils.nodes.SparseNodeVisitor

Checks if the visited option nodes and the specified args are in sync.

check_undocumented_arguments(ignored_options=None)

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.

visit_desc(node)

Skips all but ‘option’ elements

visit_desc_name(node)

Checks if the option is defined self.args

class qubes.dochelpers.VersionCheck(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

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)

Bases: docutils.nodes.warning

qubes.dochelpers.check_man_args(app, doctree, docname)

Checks the manpage for undocumented or obsolete sub-commands and options.

qubes.dochelpers.fetch_ticket_info(app, number)

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)

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