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