pydoc_markdown.contrib.processors
Module: pydoc_markdown.contrib.processors.crossref
Class CrossrefProcessor
@dataclasses.dataclass
class CrossrefProcessor(Processor)
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)
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)
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 theAttributes
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)
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)
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)
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: