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=None, section='9', manual='Kernel API Manual')

Bases: OutputFormat

Consts and functions used by man pages output.

This class has one mandatory parameter and some optional ones, which are needed to define the title header contents:

modulename

Defines the module name to be used at the troff .TH output.

This argument is optional. If not specified, it will be filled with the directory which contains the documented file.

section

Usually a numeric value from 0 to 9, but man pages also accept some strings like “p”.

Defauls to 9

manual

Defaults to Kernel API Manual.

The above controls the output of teh corresponding fields on troff title headers, which will be filled like this:

.TH "{name}" {section} "{date}" "{modulename}" "{manual}"

where name` will match the API symbol name, and date will be either the date where the Kernel was compiled or the current date

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.

code_block(lines, start)

Ensure that code blocks won’t be messed up at the output.

By default, troff join lines at the same paragraph. Disable it, on code blocks.

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.

emit_table(colspec_row, rows)

emit_th(name, args)

Emit a title header line.

grid_table(lines, start)

Ancillary function to help handling a grid table inside the text.

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

Highlights to be used in ReST format.

modulename(args)

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.

simple_table(lines, start)

Ancillary function to help handling a simple table inside the text.

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 = [(KernRe("\b``([^\`]+)``\b"), '``\\1``'), (KernRe("\%([-_*\w]+)"), '``\\1``'), (KernRe("\&([_\w]+)(\.|->)([_\w]+)\(\)"), ':c:type:`\\1\\2\\3\\\\(\\\\) <\\1>`'), (KernRe("\&([_\w]+)(\.|->)([_\w]+)"), ':c:type:`\\1\\2\\3 <\\1>`'), (KernRe("\@(\w+)\(\)"), '**\\1\\\\(\\\\)**'), (KernRe("\@(\w+->\S+)\(\)"), '**\\1\\\\(\\\\)**'), (KernRe("(\w+)\(\)"), '\\1()'), (KernRe("\&(enum\s*([_\w]+))"), ':c:type:`\\1 <\\2>`'), (KernRe("\&(struct\s*([_\w]+))"), ':c:type:`\\1 <\\2>`'), (KernRe("\&(typedef\s*([_\w]+))"), ':c:type:`\\1 <\\2>`'), (KernRe("\&(union\s*([_\w]+))"), ':c:type:`\\1 <\\2>`'), (KernRe("\&([_\w]+)"), ':c:type:`\\1`'), (KernRe("([\!~\*]?)\@(\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 = KernRe("^\.\.\ +code-block::")

Sphinx code block regex.

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

Sphinx literal block regex.