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: 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: 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: 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: Directive

Directive versioncheck

Check if current version (from conf.py) equals version specified as argument. If not, generate warning.

final_argument_whitespace = True

May the final argument contain whitespace?

has_content = True

May the directive have content?

option_spec = {}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

required_arguments = 1

Number of required directive arguments.

class qubes.dochelpers.versioncheck(rawsource: str = '', *children, **attributes: Any)

Bases: warning

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

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