Skip to content

pydoc_markdown.contrib.processors

Module: pydoc_markdown.contrib.processors.crossref

Class CrossrefProcessor

@dataclasses.dataclass
class CrossrefProcessor(Processor)

[view_source]

Finds references to other objects in Markdown docstrings and produces links to other pages. The links are provided by the current Renderer via the Resolver interface.

Note: This processor is a work in progress, and most of the time it just converts references into inline-code.

The syntax for cross references is as follows:

This is a ref to another class: [PydocmdProcessor](#pydoc:pydoc_markdown.contrib.processors.pydocmd.PydocmdProcessor)
You can rename a ref like `this`~PydocmdProcessor
And you can append to the ref name like this: [PydocmdProcessors](#pydoc:pydoc_markdown.contrib.processors.pydocmd.PydocmdProcessor)

Renders as

This is a ref to another class: PydocmdProcessor You can rename a ref like this~PydocmdProcessor And you can append to the ref name like this: PydocmdProcessors

Example configuration:

processors:
  - type: crossref

resolver_v2

If specified, it will be used instead of the resolver passed to process() and the generated Markdown code for the reference uses Novella {@link } syntax.

Module: pydoc_markdown.contrib.processors.filter

Class FilterProcessor

@dataclasses.dataclass
class FilterProcessor(Processor)

[view_source]

The filter processor removes module and class members based on certain criteria.

Example configuration:

- type: filter
  expression: not name.startswith('_') and default()
  documented_only: false

Options

expression

A Python expression that is evaluated given the variables name, obj and default and is expected to return a boolean to indicate whether the docspec.ApiObject should be kept or removed. If specified, the expression is the ultimate truth for determining the keep-or-remove state of a node. Using 'default()' as the expression has the same semantic as not specifying this field. Default: null

documented_only

Keep only API objects that have docstrings. Default: true

exclude_private

Exclude API objects that appear to be private members (i.e. their name begins with and underscore but does not end with one). Default: true

exclude_special

Exclude special members (e.g.__path__, __annotations__, __name__ and __all__). Default: true

do_not_filter_modules

Do not filter docspec.Module objects. Default: true

skip_empty_modules

Skip modules with no content. Default: false.

Module: pydoc_markdown.contrib.processors.google

Class GoogleProcessor

@dataclasses.dataclass
class GoogleProcessor(Processor)

[view_source]

This class implements the preprocessor for Google and PEP 257 docstrings. It converts docstrings formatted in the Google docstyle to Markdown syntax.

References:

  • https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
  • https://www.python.org/dev/peps/pep-0257/

Example:

Attributes:
    module_level_variable1 (int): Module level variables may be documented in
        either the ``Attributes`` section of the module docstring, or in an
        inline docstring immediately following the variable.

        Either form is acceptable, but the two should not be mixed. Choose
        one convention to document module level variables and be consistent
        with it.

Todo:
    * For module TODOs
    * You have to also use ``sphinx.ext.todo`` extension

Renders as:

Attributes:

  • module_level_variable1 int - Module level variables may be documented in either the Attributes section of the module docstring, or in an inline docstring immediately following the variable.

Either form is acceptable, but the two should not be mixed. Choose one convention to document module level variables and be consistent with it.

Todo:

  • For module TODOs
  • You have to also use sphinx.ext.todo extension

Module: pydoc_markdown.contrib.processors.pydocmd

Class PydocmdProcessor

@dataclasses.dataclass
class PydocmdProcessor(Processor)

[view_source]

The Pydoc-Markdown processor for Markdown docstrings. This processor parses docstrings formatted like the examples below and turns them into proper Markdown markup.

Examples:

# Arguments

arg1 (int): The first argument.
kwargs (dict): Keyword arguments.

# Raises
RuntimeError: If something bad happens.
ValueError: If an invalid argument is specified.

# Returns
A value.

Renders as:

Arguments

  • arg1 (int): The first argument.
  • kwargs (dict): Keyword arguments.

Raises

  • RuntimeError: If something bad happens.
  • ValueError: If an invalid argument is specified.

Returns

A value.

Module: pydoc_markdown.contrib.processors.smart

Class SmartProcessor

@dataclasses.dataclass
class SmartProcessor(Processor)

[view_source]

This processor picks the GoogleProcessor, SphinxProcessor or PydocmdProcessor after guessing which is appropriate from the syntax it finds in the docstring.

Module: pydoc_markdown.contrib.processors.sphinx

Class SphinxProcessor

@dataclasses.dataclass
class SphinxProcessor(Processor)

[view_source]

This processor parses ReST/Sphinx-style function documentation and converts it into

Markdown syntax.

Example:

**Arguments**:

- `arg1`: This is the first argument.
- `arg1`: This is the first argument.

**Raises**:

- `ValueError`: If *arg1* is a bad value.
- `ValueError`: If *arg1* is a bad value.

**Returns**:

An `int` that represents an interesting value.

Renders as: