interfaces
This module defines the interfaces that can to be implemented for Pydoc-Markdown to implement custom loaders for documentation data, processors or renderers.
Class Context
class Context()
Context data that is passed to plugins when they are loaded.
Class Loader
@Union(
[
"!pydoc_markdown.interfaces.Loader",
"<import>",
],
style=Union.FLAT,
)
class Loader(PluginBase)
This interface describes an object that is capable of loading documentation data. The location from which the documentation is loaded must be defined with the configuration class.
Class Resolver
class Resolver(abc.ABC)
A resolver can be used by a Processor to replace cross references with a hyperlink.
Class ResolverV2
class ResolverV2(abc.ABC)
New style interface for resolving based on a text ref from in the context of a docspec.ApiObject
to find another. This is different from Resolver because it returns the resolved object directly, instead
of some string representation of it.
Class Processor
@Union(
[
"!pydoc_markdown.interfaces.Processor",
"<import>",
],
style=Union.FLAT,
)
class Processor(PluginBase)
A processor is an object that takes a list of docspec.Modules as an input and
transforms it in an arbitrary way. This usually processes docstrings to convert from
various documentation syntaxes to plain Markdown.
Class Renderer
@Union(
[
"!pydoc_markdown.interfaces.Renderer",
"<import>",
],
style=Union.FLAT,
)
class Renderer(PluginBase)
A renderer is an object that takes a list of docspec.Modules as an input and produces
output files or writes to stdout. It may also expose additional command-line arguments.
There can only be one renderer at the end of the processor chain.
Note that sometimes a renderer may need to perform some processing before the render step. To keep the possibility open that a renderer may implement generic processing that could used without the actual rendering functionality, Renderer is a subclass of Processor.
Class SinglePageRenderer
class SinglePageRenderer(PluginBase)
Interface for rendering a single page.
Class SingleObjectRenderer
class SingleObjectRenderer(PluginBase)
Interface for rendering a single docspec.ApiObject.
Class Server
class Server(abc.ABC)
This interface describes an object that can start a server process for
live-viewing generated documentation in the browser. Renderer
implementations may additionally implement this interface to advocate their
compatibility with the --server and --open options of the pydoc-markdown
CLI.
reload_server
def reload_server(process: subprocess.Popen) -> subprocess.Popen
Called when the files generated by pydoc-markdown have been updated.
This gives the implementation a chance to reload the server process.
The default implementation returns the process unchanged. Returning
None will automatically call start_server() afterwards.
Class Builder
class Builder(abc.ABC)
This interface can be implemented additionally to the Renderer interface to indicate that the renderer supports building another produce after the markdown files have been rendered.
build
@abc.abstractmethod
def build(site_dir: str) -> None
Invoke the build. The site_dir is the directory in which the output files should be placed. Otherwise, the directory may be determined by the builder.
Class SourceLinker
@Union(
[
"!pydoc_markdown.interfaces.SourceLinker",
"<import>",
],
style=Union.FLAT,
)
class SourceLinker(PluginBase)
This interface is used to determine the URL to the source of an API object. Renderers can use it to place a link to the source in the generated documentation.