Kernel-doc output stage

Output handler for man pages and ReST

Classes to implement output filters to print kernel-doc documentation.

The implementation uses a virtual base class OutputFormat. It contains dispatches to virtual methods, and some code to filter out output messages.

The actual implementation is done on one separate class per each type of output, e.g. RestFormat and ManFormat classes.

Currently, there are output classes for ReST and man/troff.

class lib.python.kdoc.kdoc_output.ManFormat(modulename)

Bases: OutputFormat

Consts and functions used by man pages output.

arg_name(args, name)

Return the name that will be used for the man page.

As we may have the same name on different namespaces, prepend the data type for all types except functions and typedefs.

The doc section is special: it uses the modulename.

blankline = ''

Blank line character.

date_formats = ['%a %b %d %H:%M:%S %Z %Y', '%a %b %d %H:%M:%S %Y', '%Y-%m-%d', '%b %d %Y', '%B %d %Y', '%m %d %Y']

Allowed timestamp formats.

highlights = ((re.compile("\b``([^\`]+)``\b"), '\\1'), (re.compile("\%([-_*\w]+)"), '\\1'), (re.compile("(\w+)\(\)"), '\\\\fB\\1\\\\fP'), (re.compile("\&(enum\s*([_\w]+))"), '\\\\fI\\1\\\\fP'), (re.compile("\&(struct\s*([_\w]+))"), '\\\\fI\\1\\\\fP'), (re.compile("\&(typedef\s*([_\w]+))"), '\\\\fI\\1\\\\fP'), (re.compile("\&(union\s*([_\w]+))"), '\\\\fI\\1\\\\fP'), (re.compile("@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)"), '\\\\fI\\1\\\\fP'), (re.compile("([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)"), '\\\\fI\\1\\2\\\\fP'), (re.compile("\&([_\w]+)(\.|->)([_\w]+)"), '\\\\fI\\1\\2\\3\\\\fP'), (re.compile("\&([_\w]+)"), '\\\\fI\\1\\\\fP'))

Highlights to be used in ReST format.

msg(fname, name, args)

Handles a single entry from kernel-doc parser.

Add a tail at the end of man pages output.

out_doc(fname, name, args)

Outputs a DOC block.

out_enum(fname, name, args)

Outputs an enum.

out_function(fname, name, args)

Outputs a function.

out_struct(fname, name, args)

Outputs a struct.

out_tail(fname, name, args)

Adds a tail for all man pages.

out_typedef(fname, name, args)

Outputs a typedef.

out_var(fname, name, args)

Outputs a variable.

output_highlight(block)

Outputs a C symbol that may require being highlighted with self.highlights variable using troff syntax.

set_symbols(symbols)

Get a list of all symbols from kernel_doc.

Man pages will uses it to add a SEE ALSO section with other symbols at the same file.

class lib.python.kdoc.kdoc_output.OutputFormat

Bases: object

Base class for OutputFormat. If used as-is, it means that only warnings will be displayed.

OUTPUT_ALL = 0

Output all symbols and doc sections.

OUTPUT_EXPORTED = 2

Output exported symbols.

OUTPUT_INCLUDE = 1

Output only specified symbols.

OUTPUT_INTERNAL = 3

Output non-exported symbols.

blankline = ''

Blank line character.

check_declaration(dtype, name, args)

Checks if a declaration should be output or not based on the filtering criteria.

check_doc(name, args)

Check if DOC should be output.

highlight_block(block)

Apply the RST highlights to a sub-block of text.

highlights = []

Highlights to be used in ReST format.

msg(fname, name, args)

Handles a single entry from kernel-doc parser.

out_doc(fname, name, args)

Outputs a DOC block.

out_enum(fname, name, args)

Outputs an enum.

out_function(fname, name, args)

Outputs a function.

out_struct(fname, name, args)

Outputs a struct.

out_typedef(fname, name, args)

Outputs a typedef.

out_var(fname, name, args)

Outputs a variable.

out_warnings(args)

Output warnings for identifiers that will be displayed.

set_config(config)

Setup global config variables used by both parser and output.

set_filter(export, internal, symbol, nosymbol, function_table, enable_lineno, no_doc_sections)

Initialize filter variables according to the requested mode.

Only one choice is valid between export, internal and symbol.

The nosymbol filter can be used on all modes.

set_symbols(symbols)

Get a list of all symbols from kernel_doc.

class lib.python.kdoc.kdoc_output.RestFormat

Bases: OutputFormat

Consts and functions used by ReST output.

blankline = '\n'

Blank line character.

highlights = [(re.compile("\b``([^\`]+)``\b"), '``\\1``'), (re.compile("\%([-_*\w]+)"), '``\\1``'), (re.compile("\&([_\w]+)(\.|->)([_\w]+)\(\)"), ':c:type:`\\1\\2\\3\\\\(\\\\) <\\1>`'), (re.compile("\&([_\w]+)(\.|->)([_\w]+)"), ':c:type:`\\1\\2\\3 <\\1>`'), (re.compile("\@(\w+)\(\)"), '**\\1\\\\(\\\\)**'), (re.compile("\@(\w+->\S+)\(\)"), '**\\1\\\\(\\\\)**'), (re.compile("(\w+)\(\)"), '\\1()'), (re.compile("\&(enum\s*([_\w]+))"), ':c:type:`\\1 <\\2>`'), (re.compile("\&(struct\s*([_\w]+))"), ':c:type:`\\1 <\\2>`'), (re.compile("\&(typedef\s*([_\w]+))"), ':c:type:`\\1 <\\2>`'), (re.compile("\&(union\s*([_\w]+))"), ':c:type:`\\1 <\\2>`'), (re.compile("\&([_\w]+)"), ':c:type:`\\1`'), (re.compile("([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)"), '**\\1\\2**')]

Highlights to be used in ReST format

out_doc(fname, name, args)

Outputs a DOC block.

out_enum(fname, name, args)

Outputs an enum.

out_function(fname, name, args)

Outputs a function.

out_section(args, out_docblock=False)

Outputs a block section.

This could use some work; it’s used to output the DOC: sections, and starts by putting out the name of the doc section itself, but that tends to duplicate a header already in the template file.

out_struct(fname, name, args)

Outputs a struct.

out_typedef(fname, name, args)

Outputs a typedef.

out_var(fname, name, args)

Outputs a variable.

output_highlight(args)

Outputs a C symbol that may require being converted to ReST using the self.highlights variable.

print_lineno(ln)

Outputs a line number.

sphinx_cblock = re.compile("^\.\.\ +code-block::")

Sphinx code block regex.

sphinx_literal = re.compile("^[^.].*::$")

Sphinx literal block regex.