Welcome to the Pydoc Markdown documentation! v4.8.2-2-ge878572 (develop)
+Welcome to the Pydoc Markdown documentation! v4.8.2-3-g566847b (develop)
Pydoc-Markdown is a tool to create Python API documentation in Markdown format. Instead of executing your Python
diff --git a/search/search_index.json b/search/search_index.json
index cd396764..3db33397 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to the Pydoc Markdown documentation! v4.8.2-2-ge878572 (develop)","text":"
Pydoc-Markdown is a tool to create Python API documentation in Markdown format. Instead of executing your Python code like so many other documentation tools, it parses it using docspec instead.
\u2192 Go to the Documentation \ud83d\udcd8
Table of Contents
- Installation \ud83d\udce6
- Features \ud83c\udf1f
- News \ud83d\udce2
- 4.7.0 (Undeprecating YAML configuration)
- 4.6.0 (Novella integration)
- Contributing to Pydoc-Markdown \ud83e\udd1d
- Questions / Need help? \ud83e\udd14
- Projects using Pydoc-Markdown \ud83d\udcda
You can install Pydoc-Markdown using Pipx:
$ pipx install pydoc-markdown\nIf you plan on using the Novella integration, you may want to install it as:
$ pipx install novella\n$ pipx inject novella pydoc-markdown[novella]\nYou need at least Python 3.7 to run Pydoc-Markdown. The Python version compatibility of the package you are looking to generate documentation for is irrelevant.
"},{"location":"#features","title":"Features \ud83c\udf1f","text":"- Understands multiple documentation styles (Sphinx, Google, Pydoc-Markdown specific) and converts them to properly formatted Markdown
- Can parse docstrings for variables thanks to docspec (
#:block before or string literal after the statement) - Generates links to other API objects per the documentation syntax (e.g.
#OtherClassfor the Pydoc-Markdown style) - Configure the output using a YAML file or
pyProject.toml, then you're only one command away to generate the documentation in Markdown format - Or use Novella to tightly integrate with static site generators like MkDocs and Hugo with with additional features such as Markdown pre-processing
Many users prefer the YAML configuration over the using Novella, which is why starting with 4.7.0, the YAML style configuration is officially un-deprecated and will continue to be supported.
"},{"location":"#460-novella-integration","title":"4.6.0 (Novella integration)","text":"Starting with 4.6.0, development focuses on integrating with Novella and use it as a replacement for tool-specific renderers thus far provided directly by Pydoc-Markdown (i.e. integrations with MkDocs, Hugo and Docusuraus). Such integrations are/will be provided by Novella instead.
With the Novella integration, you can now place generated API content in Markdown format inline with your existing Markdown documentation source files using @pydoc tags. Check out the Documentation for more information on how to use Pydoc-Markdown with Novella.
The old style of using Pydoc-Markdown with a YAML or PyProject configuration to generate files and kick off the build is now deprecated but will be maintained for the foreseeable future (at least until the next major version bump). It is strongly recommended to migrate your existing projects to using the Novella build backend.
"},{"location":"#contributing-to-pydoc-markdown","title":"Contributing to Pydoc-Markdown \ud83e\udd1d","text":"All contributions are welcome! Check out the Contribution Guidelines.
"},{"location":"#questions-need-help","title":"Questions / Need help? \ud83e\udd14","text":"Feel free to open a topic on GitHub Discussions!
"},{"location":"#projects-using-pydoc-markdown","title":"Projects using Pydoc-Markdown \ud83d\udcda","text":"An incomplete list of projects that use Pydoc-Markdown to generate their API documentation. Feel free to open a pull request to add your project to this list!
- CosmPy
- haystack by deepset
- tensorchord/envd
- tqdm
Contributions to Pydoc-Markdown are very welcome!
If you want to talk about a potential contribution before investing any time, please do create a new topic on GitHub Discussions.
"},{"location":"contributing/#pull-request-requirements","title":"Pull request requirements","text":"- Please look to adhere to the existing code style (2-space indendation, 120 character line length limit)
- Pull requests should contain at least one new changelog entry unless the change is trivial (see below for details)
Pydoc-Markdown uses Slam to manage changelogs. You should use the Slam CLI to add a new changelog entry, otherwise you need to manually generate a UUID-4.
$ slap changelog add -t <type> -d <changelog message> [--issue <issue_url>]\nAfter you create the pull request, GitHub Actions will take care of injecting the PR URL into the changelog entry.
"},{"location":"api/cli/","title":"Command-line interface","text":"Usage: pydoc-markdown [OPTIONS] [CONFIG]\n\n Pydoc-Markdown is a renderer for Python API documentation in Markdown\n format.\n\n With no arguments it will load the default configuration file. If the\n *config* argument is specified, it must be the name of a configuration file\n or a YAML formatted object for the configuration.\n\nOptions:\n --version Show the version and exit.\n --bootstrap [base|mkdocs|hugo|readthedocs|docusaurus]\n Create a Pydoc-Markdown configuration file\n in the current working directory.\n -v, --verbose Increase log verbosity.\n -q, --quiet Decrease the log verbosity.\n -m, --module MODULE The module to parse and generated API\n documentation for. Can be specified multiple\n times. Using this option will disable\n loading the default configuration file.\n -p, --package PACKAGE The package to parse and generated API\n documentation for including all sub-packages\n and -modules. Can be specified multiple\n times. Using this option will disable\n loading the default configuration file.\n -I, --search-path PATH A directory to use in the search for Python\n modules. Can be specified multiple times.\n Using this option will disable loading the\n default configuration file.\n --py2 / --py3 Switch between parsing Python 2 and Python 3\n code. The default is Python 3. Using --py2\n will enable parsing code that uses the\n \"print\" statement. This is equivalent of\n setting the print_function option of the\n \"python\" loader to False. Using this option\n will disable loading the default\n configuration file.\n --render-toc / --no-render-toc Enable/disable the rendering of the TOC in\n the \"markdown\" renderer.\n -s, --server Watch for file changes and re-render if\n needed and start the server for the\n configured renderer. This doesn't work for\n all renderers.\n -o, --open Open the browser after starting the server\n with -s,--server.\n --dump Dump the loaded modules in Docspec JSON\n format to stdout, after the processors.\n --with-processors / --without-processors\n Enable/disable processors. Only with --dump.\n --build Invoke a build after the Markdown files are\n produced. Note that some renderers may not\n support this option (e.g. the \"markdown\"\n renderer).\n --site-dir TEXT Set the output directory when using --build.\n --help Show this message and exit.\nVersion: pydoc-markdown, version 4.8.2
@dataclasses.dataclass\nclass PydocMarkdown()\n[view_source]
This object represents the main configuration for Pydoc-Markdown.
"},{"location":"api/pydoc_markdown/#loaders","title":"loaders","text":"A list of loader implementations that load docspec.Modules. Defaults to PythonLoader.
A list of processor implementations that modify docspec.Modules. Defaults to FilterProcessor, SmartProcessor and CrossrefProcessor.
A renderer for docspec.Modules. Defaults to MarkdownRenderer.
Hooks that can be executed at certain points in the pipeline. The commands are executed with the current SHELL.
def load_config(arg: t.Union[str, dict]) -> None\n[view_source]
Loads the configuration from a nested data structure or filename as specified per the data
argument. If a filename is specified, it may be a JSON, YAML or TOML file. If the name of the TOML file is pyproject.yoml, the configuration will be read from the [tool.pydoc-markdown] section.
Arguments:
data: A nested structure or the path to a configuration file.
def init(context: Context) -> None\n[view_source]
Initialize all plugins with the specified context. Cannot be called multiple times. If omitted, the plugins will be initialized with a default context before the load, process or render phase.
"},{"location":"api/pydoc_markdown/#load_modules","title":"load_modules","text":"def load_modules() -> t.List[docspec.Module]\n[view_source]
Loads modules via the loaders.
"},{"location":"api/pydoc_markdown/#process","title":"process","text":"def process(modules: t.List[docspec.Module]) -> None\n[view_source]
Process modules via the processors.
"},{"location":"api/pydoc_markdown/#render","title":"render","text":"def render(modules: t.List[docspec.Module], run_hooks: bool = True) -> None\n[view_source]
Render modules via the renderer.
"},{"location":"api/pydoc_markdown/interfaces/","title":"interfaces","text":"This module defines the interfaces that can to be implemented for Pydoc-Markdown to implement custom loaders for documentation data, processors or renderers.
"},{"location":"api/pydoc_markdown/interfaces/#class-context","title":"Class Context","text":"class Context()\n[view_source]
Context data that is passed to plugins when they are loaded.
"},{"location":"api/pydoc_markdown/interfaces/#class-loader","title":"Class Loader","text":"@Union(\n [\n \"!pydoc_markdown.interfaces.Loader\",\n \"<import>\",\n ],\n style=Union.FLAT,\n)\nclass Loader(PluginBase)\n[view_source]
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.
"},{"location":"api/pydoc_markdown/interfaces/#class-resolver","title":"Class Resolver","text":"class Resolver(abc.ABC)\n[view_source]
A resolver can be used by a Processor to replace cross references with a hyperlink.
"},{"location":"api/pydoc_markdown/interfaces/#class-resolverv2","title":"Class ResolverV2","text":"class ResolverV2(abc.ABC)\n[view_source]
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.
@Union(\n [\n \"!pydoc_markdown.interfaces.Processor\",\n \"<import>\",\n ],\n style=Union.FLAT,\n)\nclass Processor(PluginBase)\n[view_source]
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.
@Union(\n [\n \"!pydoc_markdown.interfaces.Renderer\",\n \"<import>\",\n ],\n style=Union.FLAT,\n)\nclass Renderer(PluginBase)\n[view_source]
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.
"},{"location":"api/pydoc_markdown/interfaces/#class-singlepagerenderer","title":"Class SinglePageRenderer","text":"class SinglePageRenderer(PluginBase)\n[view_source]
Interface for rendering a single page.
"},{"location":"api/pydoc_markdown/interfaces/#class-singleobjectrenderer","title":"Class SingleObjectRenderer","text":"class SingleObjectRenderer(PluginBase)\n[view_source]
Interface for rendering a single docspec.ApiObject.
class Server(abc.ABC)\n[view_source]
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.
def reload_server(process: subprocess.Popen) -> subprocess.Popen\n[view_source]
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(abc.ABC)\n[view_source]
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.
"},{"location":"api/pydoc_markdown/interfaces/#build","title":"build","text":"@abc.abstractmethod\ndef build(site_dir: str) -> None\n[view_source]
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.
"},{"location":"api/pydoc_markdown/interfaces/#class-sourcelinker","title":"Class SourceLinker","text":"@Union(\n [\n \"!pydoc_markdown.interfaces.SourceLinker\",\n \"<import>\",\n ],\n style=Union.FLAT,\n)\nclass SourceLinker(PluginBase)\n[view_source]
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.
"},{"location":"api/pydoc_markdown/loaders/","title":"pydoc_markdown.contrib.loaders.python","text":""},{"location":"api/pydoc_markdown/loaders/#class-pythonloader","title":"Class PythonLoader","text":"@dataclasses.dataclass\nclass PythonLoader(Loader)\n[view_source]
This implementation of the Loader interface parses Python modules and packages using docspec_python. See the options below to control which modules and packages are being loaded and how to configure the parser.
With no modules or packages set, the PythonLoader will discover available modules in the current and src/ directory.
lib2to3 Quirks
Pydoc-Markdown doesn't execute your Python code but instead relies on the lib2to3 parser. This means it also inherits any quirks of lib2to3.
List of known quirks
- A function argument in Python 3 cannot be called
printeven though it is legal syntax
A list of package names that this loader will search for and then parse, including all sub-packages and modules.
"},{"location":"api/pydoc_markdown/loaders/#search_path","title":"search_path","text":"The module search path. If not specified, the current sys.path is used instead. If any of the elements contain a * (star) symbol, it will be expanded with sys.path.
List of modules to ignore when using module discovery on the search_path.
"},{"location":"api/pydoc_markdown/loaders/#parser","title":"parser","text":"Options for the Python parser.
"},{"location":"api/pydoc_markdown/loaders/#encoding","title":"encoding","text":"The encoding to use when reading the Python source files.
Changed in 4.7.0: Default changed from None (system default encoding) to \"utf-8\".
Module: pydoc_markdown.contrib.processors.crossref
@dataclasses.dataclass\nclass CrossrefProcessor(Processor)\n[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)\nYou can rename a ref like `this`~PydocmdProcessor\nAnd you can append to the ref name like this: [PydocmdProcessors](#pydoc:pydoc_markdown.contrib.processors.pydocmd.PydocmdProcessor)\nRenders 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:\n - type: crossref\nIf 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
@dataclasses.dataclass\nclass FilterProcessor(Processor)\n[view_source]
The filter processor removes module and class members based on certain criteria.
Example configuration:
- type: filter\n expression: not name.startswith('_') and default()\n documented_only: false\nA 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
Keep only API objects that have docstrings. Default: true
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 members (e.g.__path__, __annotations__, __name__ and __all__). Default: true
Do not filter docspec.Module objects. Default: true
Skip modules with no content. Default: false.
Module: pydoc_markdown.contrib.processors.google
@dataclasses.dataclass\nclass GoogleProcessor(Processor)\n[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:\n module_level_variable1 (int): Module level variables may be documented in\n either the ``Attributes`` section of the module docstring, or in an\n inline docstring immediately following the variable.\n\n Either form is acceptable, but the two should not be mixed. Choose\n one convention to document module level variables and be consistent\n with it.\n\nTodo:\n * For module TODOs\n * You have to also use ``sphinx.ext.todo`` extension\nRenders as:
Attributes:
module_level_variable1int - Module level variables may be documented in either theAttributessection 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.todoextension
Module: pydoc_markdown.contrib.processors.pydocmd
@dataclasses.dataclass\nclass PydocmdProcessor(Processor)\n[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\n\narg1 (int): The first argument.\nkwargs (dict): Keyword arguments.\n\n# Raises\nRuntimeError: If something bad happens.\nValueError: If an invalid argument is specified.\n\n# Returns\nA value.\nRenders 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
@dataclasses.dataclass\nclass SmartProcessor(Processor)\n[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
@dataclasses.dataclass\nclass SphinxProcessor(Processor)\n[view_source]
This processor parses ReST/Sphinx-style function documentation and converts it into
Markdown syntax.
Example:
**Arguments**:\n\n- `arg1`: This is the first argument.\n- `arg1`: This is the first argument.\n\n**Raises**:\n\n- `ValueError`: If *arg1* is a bad value.\n- `ValueError`: If *arg1* is a bad value.\n\n**Returns**:\n\nAn `int` that represents an interesting value.\nRenders as:
"},{"location":"api/pydoc_markdown/renderers/docusaurus/","title":"docusaurus","text":""},{"location":"api/pydoc_markdown/renderers/docusaurus/#class-customizedmarkdownrenderer","title":"Class CustomizedMarkdownRenderer","text":"@dataclasses.dataclass\nclass CustomizedMarkdownRenderer(MarkdownRenderer)\n[view_source]
We override some defaults in this subclass.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#insert_header_anchors","title":"insert_header_anchors","text":"Disabled because Docusaurus supports this automatically.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#escape_html_in_docstring","title":"escape_html_in_docstring","text":"Escape html in docstring, otherwise it could lead to invalid html.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#render_module_header_template","title":"render_module_header_template","text":"Conforms to Docusaurus header format.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#class-docusaurusrenderer","title":"Class DocusaurusRenderer","text":"@dataclasses.dataclass\nclass DocusaurusRenderer(Renderer)\n[view_source]
Produces Markdown files and a sidebar.json file for use in a Docusaurus v2 websites. It creates files in a fixed layout that reflects the structure of the documented packages. The files will be rendered into the directory specified with the docs_base_path option.
Check out the complete Docusaurus example on GitHub.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#options","title":"Options","text":""},{"location":"api/pydoc_markdown/renderers/docusaurus/#markdown","title":"markdown","text":"The MarkdownRenderer configuration.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#docs_base_path","title":"docs_base_path","text":"The path where the docusaurus docs content is. Defaults \"docs\" folder.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#relative_output_path","title":"relative_output_path","text":"The output path inside the docs_base_path folder, used to output the module reference.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#relative_sidebar_path","title":"relative_sidebar_path","text":"The sidebar path inside the docs_base_path folder, used to output the sidebar for the module reference.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#sidebar_top_level_label","title":"sidebar_top_level_label","text":"The top-level label in the sidebar. Default to 'Reference'. Can be set to null to remove the sidebar top-level all together. This option assumes that there is only one top-level module.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#sidebar_top_level_module_label","title":"sidebar_top_level_module_label","text":"The top-level module label in the sidebar. Default to null, meaning that the actual module name will be used. This option assumes that there is only one top-level module.
"},{"location":"api/pydoc_markdown/renderers/hugo/","title":"hugo","text":""},{"location":"api/pydoc_markdown/renderers/hugo/#class-hugopage","title":"Class HugoPage","text":"@dataclasses.dataclass\nclass HugoPage(GenericPage[\"HugoPage\"])\n[view_source]
A subclass of {@link pydoc:pydoc_markdown.util.pages.Page} which adds Hugo-specific overrides.
"},{"location":"api/pydoc_markdown/renderers/hugo/#options","title":"Options","text":""},{"location":"api/pydoc_markdown/renderers/hugo/#preamble","title":"preamble","text":"The Hugo preamble of the page. This is merged with the HugoRenderer.default_preamble.
"},{"location":"api/pydoc_markdown/renderers/hugo/#directory","title":"directory","text":"Override the directory that this page is rendered into (relative to the content directory). Defaults to null.
@dataclasses.dataclass\nclass HugoConfig()\n[view_source]
Represents the Hugo configuration file that is rendered into the build directory.
"},{"location":"api/pydoc_markdown/renderers/hugo/#options_1","title":"Options","text":""},{"location":"api/pydoc_markdown/renderers/hugo/#title","title":"title","text":"Title of the site. This is a mandatory field.
"},{"location":"api/pydoc_markdown/renderers/hugo/#theme","title":"theme","text":"The theme of the site. This is a mandatory field. It must be a string, a HugoThemePath or a HugoThemeGitUrl object. Examples:
theme: antarctica\ntheme: {clone_url: \"https://github.com/alex-shpak/hugo-book.git\"}\ntheme: docs/hugo-theme/\nBase URL.
"},{"location":"api/pydoc_markdown/renderers/hugo/#serverurl","title":"serverURL","text":"Server URL. Default: 127.0.0.1 aka localhost
Server Port. Default: 1313
Language code. Default: en-us
@dataclasses.dataclass\nclass HugoRenderer(Renderer, Server, Builder)\n[view_source]
A renderer that produces Markdown files compatible with Hugo. The --bootstrap hugo option can be used to create a Pydoc-Markdown configuration file with the Hugo template.
- Adds a YAML preamble to every generated Markdown file.
- Produces files in a layout suitable for Hugo (e.g.
_index.mdfiles). - Produces a
config.yamlif config is not set tonull. - Can be used with the Pydoc-Markdown
--serveroption to live-preview the generated docs. - Downloads a suitable Hugo binary from Github if Hugo is not already installed (see get_hugo).
Example configuration:
renderer:\n type: hugo\n config:\n title: My Project\n theme: {clone_url: \"https://github.com/alex-shpak/hugo-book.git\"}\n # The \"book\" theme only renders pages in \"content/docs\" into the nav.\n content_directory: content/docs\n default_preamble: {menu: main}\n pages:\n - title: Home\n name: index\n source: README.md\n - title: API Documentation\n contents:\n - '*'\nThe directory where all generated files are placed. Default: build/docs
The directory inside the build directory where the generated pages are written to. Default: content
Clean up files that were previously generated by the renderer before the next render pass. Defaults to True.
The pages to render.
"},{"location":"api/pydoc_markdown/renderers/hugo/#default_preamble","title":"default_preamble","text":"The default Hugo preamble that is applied to every page. Example:
default_preamble:\n menu: main\nThe MarkdownRenderer configuration.
"},{"location":"api/pydoc_markdown/renderers/hugo/#config","title":"config","text":"The contents of the Hugo config.toml file as YAML. This can be set to null in order to not produce the config.toml file in the build_directory. Must be deserializable into a HugoConfig.
Options for when the Hugo binary is not present and should be downloaded automatically. Example:
get_hugo:\n enabled: true\n version: '0.71'\n extended: true\ndef install_hugo(to: str,\n version: str | None = None,\n extended: bool = True) -> None\n[view_source]
Downloads the latest release of Hugo from Github
and places it at the path specified by to. This will install the extended version if it is available and extended is set to True.
Arguments:
to: The file to write the Hugo binary to.version: The Hugo version to get. If not specified, the latest release will be used.extended: Whether to download the \"Hugo extended\" version. Defaults to True.
def get_github_releases(repo: str) -> t.Generator[dict, None, None]\n[view_source]
Returns an iterator for all releases of a Github repository.
"},{"location":"api/pydoc_markdown/renderers/hugo/#parse_links_header","title":"parse_links_header","text":"def parse_links_header(link_header: str) -> t.Dict[str, str]\n[view_source]
Parses the Link HTTP header and returns a map of the links. Logic from PageLinks.java.
at any point on future Pydoc-Markdown versions.
"},{"location":"api/pydoc_markdown/renderers/jinja2/#class-renderblock","title":"Class RenderBlock","text":"@D.dataclass\nclass RenderBlock()\n[view_source]
"},{"location":"api/pydoc_markdown/renderers/jinja2/#template","title":"template","text":"The path to the Jinja2 template that is used to render the output files.
"},{"location":"api/pydoc_markdown/renderers/jinja2/#produces","title":"produces","text":"A mapping for filename (without suffix) to a list of Module selectors.
"},{"location":"api/pydoc_markdown/renderers/jinja2/#jinja2_environment_settings","title":"jinja2_environment_settings","text":"Settings for the Jinja2 Environment.
"},{"location":"api/pydoc_markdown/renderers/jinja2/#class-jinja2renderer","title":"Class Jinja2Renderer","text":"@D.dataclass\nclass Jinja2Renderer(Renderer)\n[view_source]
"},{"location":"api/pydoc_markdown/renderers/jinja2/#renders","title":"renders","text":"Render instructions.
"},{"location":"api/pydoc_markdown/renderers/jinja2/#build_directory","title":"build_directory","text":"Build directory where all the files are produced.
"},{"location":"api/pydoc_markdown/renderers/markdown/","title":"markdown","text":""},{"location":"api/pydoc_markdown/renderers/markdown/#class-markdownrenderer","title":"Class MarkdownRenderer","text":"@dataclasses.dataclass\nclass MarkdownRenderer(Renderer, SinglePageRenderer, SingleObjectRenderer)\n[view_source]
Produces Markdown files. This renderer is often used by other renderers, such as MkdocsRenderer and HugoRenderer. It provides a wide variety of options to customize the generated Markdown files.
"},{"location":"api/pydoc_markdown/renderers/markdown/#options","title":"Options","text":""},{"location":"api/pydoc_markdown/renderers/markdown/#filename","title":"filename","text":"The name of the file to render to. If no file is specified, it will render to stdout.
"},{"location":"api/pydoc_markdown/renderers/markdown/#encoding","title":"encoding","text":"The encoding of the output file. This is ignored when rendering to stdout.
"},{"location":"api/pydoc_markdown/renderers/markdown/#insert_header_anchors","title":"insert_header_anchors","text":"If enabled, inserts anchors before Markdown headers to ensure that links to the header work. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#html_headers","title":"html_headers","text":"Generate HTML headers instead of Mearkdown headers. This is disabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#code_headers","title":"code_headers","text":"Render names in headers as code (using backticks or <code> tags, depending on html_headers). This is enabled by default.
Generate descriptive class titles by adding the word \"Objects\" if set to True. Otherwise, it can be a string that is appended or prepended (appended if the string begins with $). the class name. This is enabled by default.
Generate descriptivie module titles by adding the word \"Module\" before the module name. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#add_module_prefix","title":"add_module_prefix","text":"Add the module name as a prefix to class & method names. This module name is also rendered as code if code_headers is enabled. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#add_method_class_prefix","title":"add_method_class_prefix","text":"Add the class name as a prefix to method names. This class name is also rendered as code if code_headers is enabled. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#add_member_class_prefix","title":"add_member_class_prefix","text":"Add the class name as a prefix to member names. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#add_full_prefix","title":"add_full_prefix","text":"Add the full module name as a prefix to the title of the header. This is disabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#sub_prefix","title":"sub_prefix","text":"If add_full_prefix is enabled, this will result in the prefix to be wrapped in a <sub> tag.
Render the definition of data members as a code block. This is disabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#data_expression_maxlength","title":"data_expression_maxlength","text":"Max length of expressions. If this limit is exceeded, the remaining characters will be replaced with three dots. This is set to 100 by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#classdef_code_block","title":"classdef_code_block","text":"Render the class signature as a code block. This includes the \"class\" keyword, the class name and its bases. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#classdef_with_decorators","title":"classdef_with_decorators","text":"Render decorators before class definitions.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_python_help_style","title":"signature_python_help_style","text":"Render classdef and function signature blocks in the Python help() style.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_code_block","title":"signature_code_block","text":"Render the function signature as a code block. This includes the \"def\" keyword, the function name and its arguments. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_in_header","title":"signature_in_header","text":"Render the function signature in the header. This is disabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_with_vertical_bar","title":"signature_with_vertical_bar","text":"Render the vertical bar '|' before function signature. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_with_def","title":"signature_with_def","text":"Include the \"def\" keyword in the function signature. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_class_prefix","title":"signature_class_prefix","text":"Render the class name in the code block for function signature. Note that this results in invalid Python syntax to be rendered. This is disabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_with_decorators","title":"signature_with_decorators","text":"Render decorators before function definitions.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_typehint_in_data_header","title":"render_typehint_in_data_header","text":"Render type hints for data elements in the header.
"},{"location":"api/pydoc_markdown/renderers/markdown/#code_lang","title":"code_lang","text":"Add the string \"python\" after the backticks for code blocks. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_page_title","title":"render_page_title","text":"Render title of page at the beginning of the file.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_toc","title":"render_toc","text":"Render a table of contents at the beginning of the file.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_toc_title","title":"render_toc_title","text":"The title of the \"Table of Contents\" header.
"},{"location":"api/pydoc_markdown/renderers/markdown/#toc_maxdepth","title":"toc_maxdepth","text":"The maximum depth of the table of contents. Defaults to 2.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_module_header","title":"render_module_header","text":"Render module headers. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_module_header_template","title":"render_module_header_template","text":"Custom template for module header.
"},{"location":"api/pydoc_markdown/renderers/markdown/#docstrings_as_blockquote","title":"docstrings_as_blockquote","text":"Render docstrings as blockquotes. This is disabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#use_fixed_header_levels","title":"use_fixed_header_levels","text":"Use a fixed header level for every kind of API object. The individual levels can be defined with header_level_by_type.
"},{"location":"api/pydoc_markdown/renderers/markdown/#header_level_by_type","title":"header_level_by_type","text":"Fixed header levels by API object type.
"},{"location":"api/pydoc_markdown/renderers/markdown/#source_linker","title":"source_linker","text":"A plugin that implements the SourceLinker interface to provide links to the source code of API objects. If this field is specified, the renderer will place links to the source code in the generated Markdown files.
"},{"location":"api/pydoc_markdown/renderers/markdown/#source_format","title":"source_format","text":"Allows you to override how the \"view source\" link is rendered into the Markdown file if a source_linker is configured. The default is [[view_source]]({url}).
Escape html in docstring. Default to False.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_novella_anchors","title":"render_novella_anchors","text":"Render Novella @anchor tags before headings.
Format code rendered into Markdown code blocks with YAPF.
"},{"location":"api/pydoc_markdown/renderers/markdown/#format_code_style","title":"format_code_style","text":"The style to format code as. This can be a YAPF builtin style name or point to a file relative to the context directory (usually the working directory).
"},{"location":"api/pydoc_markdown/renderers/markdown/#get_resolver","title":"get_resolver","text":"def get_resolver(modules: t.List[docspec.Module]) -> t.Optional[Resolver]\n[view_source]
Returns a simple Resolver implementation. Finds cross-references in the same file.
"},{"location":"api/pydoc_markdown/renderers/markdown/#class-markdownreferenceresolver","title":"Class MarkdownReferenceResolver","text":"@dataclasses.dataclass\nclass MarkdownReferenceResolver(Resolver, ResolverV2)\n[view_source]
"},{"location":"api/pydoc_markdown/renderers/markdown/#resolve_reference","title":"resolve_reference","text":"def resolve_reference(suite: ApiSuite, scope: docspec.ApiObject,\n ref: str) -> t.Optional[docspec.ApiObject]\n[view_source]
Resolves the reference by searching in the members of scope or any of its parents.
"},{"location":"api/pydoc_markdown/renderers/mkdocs/","title":"mkdocs","text":""},{"location":"api/pydoc_markdown/renderers/mkdocs/#class-customizedmarkdownrenderer","title":"Class CustomizedMarkdownRenderer","text":"@dataclasses.dataclass\nclass CustomizedMarkdownRenderer(MarkdownRenderer)\n[view_source]
We override some defaults in this subclass.
"},{"location":"api/pydoc_markdown/renderers/mkdocs/#class-mkdocsrenderer","title":"Class MkdocsRenderer","text":"@dataclasses.dataclass\nclass MkdocsRenderer(Renderer, Server, Builder)\n[view_source]
Produces Markdown files in a layout compatible with [MkDocs][0] and can be used with the Pydoc-Markdown --server option for a live-preview. The --bootstrap mkdocs option can be used to create a Pydoc-Markdown configuration file with the MkDocs template.
Example configuration:
renderer:\n type: mkdocs\n pages:\n - title: Home\n name: index\n source: README.md\n - title: API Documentation\n contents:\n - '*'\n mkdocs_config:\n site_name: My Project\n theme: readthedocs\nThe output directory for the generated Markdown files. Defaults to build/docs.
Name of the content directory (inside the output_directory). Defaults to \"content\".
"},{"location":"api/pydoc_markdown/renderers/mkdocs/#clean_render","title":"clean_render","text":"Remove files generated in a previous pass by the Mkdocs renderer before rendering again. Defaults to True.
Markdown renderer settings.
"},{"location":"api/pydoc_markdown/renderers/mkdocs/#site_name","title":"site_name","text":"The name of the site. This will be carried into the site_name key of the mkdocs_config.
Arbitrary configuration values that will be rendered to an mkdocs.yml file.
Port for the Mkdocs server when using the pydoc-markdown --server option. Defaults to 8000. Can be set with the MKDOCS_PORT environment variable:
$ MKDOCS_PORT=8383 pydoc-markdown -so\nbaseURL","text":"When using Hugo, usually you want to set the baseURL configuration so that it can generated permalinks properly. If you are building on Read the Docs, chances are that you will have multiple versions of the documentation, which all require a different baseURL.
Pydoc-Markdown configuration files are pre-processed with a YTT-like templating language.
#@ def base_url():\n#@ if env.READTHEDOCS:\n#@ return \"https://pydoc-markdown.readthedocs.io/en/\" + env.READTHEDOCS_VERSION + \"/\"\n#@ else:\n#@ return None\n#@ end\n\nrenderer:\n type: hugo\n config:\n baseURL: #@ base_url()\nUsing Pydoc-Markdown on readthedocs.org requires some \"hacking\" because natively it does not allow you to run any custom commands. Using readthedocs-custom-steps, you can hook into the call that RTD expects to generate the documentation using Sphinx/MkDocs and run your own commands instead.
Example
.readthedocs.ymlsetup.cfgpyproject.tomlversion: 2\nmkdocs: {} # tell readthedocs to use mkdocs\npython:\n version: 3.7\n install:\n - method: pip\n extra_requirements:\n - rtd\n[options.extras_require]\nrtd = readthedocs-custom-steps==0.6.2\n# ...\n\n[tool.readthedocs-custom-steps]\nscript = \"\"\"\nnovella --site-dir _site/html\n\"\"\"\nIf you only want to use Pydoc-Markdown to generate Markdown from Python code, but not use it for anything else (such as interfacing with a static site generator), you can of course do that. You can make use of the Class PythonLoader and Class MarkdownRenderer, or more conveniently the Class PydocMarkdown APIs, or use the CLI.
"},{"location":"usage/cli-and-api/#cli-example","title":"CLI Example","text":"The Pydoc-Markdown CLI accepts some options that can modify the default configuration (i.e. the Python loader and Markdown renderer) and write the generated Markdown to stdout.
pydoc-markdown -I src -m package_name.module_name --render-toc > module_name.md\nYou can also supply a YAML configuration as a positional argument that will be treated the same way as if it was loaded from a pydoc-markdown.yml file.
pydoc-markdown -m my_module '{\n renderer: {\n type: markdown,\n descriptive_class_title: false,\n render_toc: true\n }\n }' > my_module.md\nfrom pydoc_markdown.interfaces import Context\nfrom pydoc_markdown.contrib.loaders.python import PythonLoader\nfrom pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer\n\ncontext = Context(directory='.')\nloader = PythonLoader(search_path=['src'])\nrenderer = MarkdownRenderer(render_module_header=False)\n\nloader.init(context)\nrenderer.init(context)\n\nmodules = loader.load()\nprint(renderer.render_to_string(modules))\nNote
This does not include any filtering logic and will just render every member in your Python code.
from pydoc_markdown import PydocMarkdown\nfrom pydoc_markdown.contrib.loaders.python import PythonLoader\nfrom pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer\n\nsession = PydocMarkdown() # Preconfigured with a PythonLoader, FilterProcessor, CrossRefProcess, SmartProcessor and MarkdownRenderer\n\nassert isinstance(session.loaders[0], PythonLoader)\nsession.loaders[0].search_path = [\"src\"]\n\nassert isinstance(session.renderer, MarkdownRenderer)\nsession.renderer.render_to_string(session.process(session.load_modules()))\nWhen using the Pydoc-Markdown integration with Novella to make use of its Markdown pre-processing capabilities, Pydoc-Markdown comes as a plugin that provides a @pydoc and @pylink tag to insert Markdown documentation generated by Pydoc-Markdown in the corresponding places of your documentation.
When using Pipx, the recommended installation method is to inject Pydoc-Markdown later:
$ pipx install novella\n$ pipx inject novella pydoc-markdown[novella]\nIf you manage the environment yourself, it's sufficient to install Pydoc-Markdown with the novella extra.
$ pip install pydoc-markdown[novella]\nA Novella build is configured using a build.novella script. In most cases you want to rely on a template provided by Novella, such as the MkDocs template. Check out the Novella documentation to find what types of templates are available here.
template \"mkdocs\" {\n content_directory = \"content\"\n}\n\naction \"preprocess-markdown\" {\n use \"pydoc\"\n}\nWhat is happening here?
- The
mkdocspipeline template is applied. Thecontent_directoryis the directory that contains your MkDocs source files. It will be copied to the temporary build location alongside themkdocs.ymlfile. Note that yourbuild.novellascript should sit next two these files.
Note: You should have mkdocs on your PATH and it should have the mkdocs-material theme installed (the default theme that Novella will apply if you don't specify a different one in your mkdocs.yml file or in build.novella).
- The
preprocess-markdownaction that is one of the actions created by the template is retrieved and configured further. We instruct it to make use of the\"pydoc\"plugin, which is implemented by Pydoc-Markdown and provides the@pydocand{@link pydoc:}tags.
Note
-
The
content/directory is the default so it does not need to be set explicitly and it is sufficient to writetemplate \"mkdocs\"(without an empty configuration block). -
The
mkdocstemplate will apply a default configuration delivered with Novella to your MkDocs configuration. If you don't want this, you can configure the\"mkdocs-update-config\"action to disable this. Note that you can also have no MkDocs configuration file and the template will create a default file for you. -
The
pydoctag is implemented in {@link pydoc:pydoc_markdown.novella.preprocessor.PydocTagPreprocessor}. Look it up to understand how it can be configured further. -
The
pydoctag processor applies a heuristic to populate the default search path for your Python source code. If the directory in which the build is executed is calleddocsordocumentation, it will default to[ \"../src\", \"..\" ], otherwise it will default to[ \"src\", \".\" ].
For example, the @cat tag is useful to inject the content of another file.
# Welcome to my Project documentation!\n\n@cat ../../readme.md :with slice_lines = \"2:\"\nThe @pydoc tag is the piece provided by Pydoc-Markdown itself. It uses the Class MarkdownRenderer to generate Markdown formatted API documentation of the API object you specify.
# API Documentation\n\n@pydoc my_module.SomeClass\nChange into the docs/ directory where your build.novella script resides and invoke the Novella CLI. The MkDocs template exposes some command-line arguments that you can pass through the CLI, one of which is the --serve option that runs MkDocs in the server mode instead of building the documentation and writing it to disk.
usage: novella [--version] [-h] [-i TEMPLATE] [-c PATH] [-d DIRECTORY]\n [-b PATH] [-r] [--dot] [--intercept ACTION] [--serve]\n [--port PORT] [--site-dir PATH] [--base-url URL]\n\noptions:\n --version show program's version number and exit\n -h, --help Show this help output.\n -i TEMPLATE, --init TEMPLATE\n Create a `build.novella` file initialized from a\n template. Available templates are: \"mkdocs\", \"hugo\"\n -c PATH, --config-file PATH\n The configuration file to load. Can be a\n pyproject.toml in which case the code is looked up\n under the tool.novella.script key. (default: None)\n -d DIRECTORY, --directory DIRECTORY\n Switch to the specified directory before executing the\n configuration file.\n -b PATH, --build-directory PATH\n The build directory. If not specified, a temporary\n directory will be created.\n -r, --use-reloader Enable reloading, which will re-execute the pipeline\n if a watched file changes.\n --dot Produce a DotViz representation of the build graph.\n --intercept ACTION The name of an action to intercept and pause the\n execution, waiting for user input to continue. Useful\n for debugging intermediate steps of the build process.\n Currently, the action name must be matched exactly and\n actions can only be intercepted before they are run.\n If this option is provided, all possible intercept\n points are logged to the console.\n\ntemplate (mkdocs):\n --serve Use mkdocs serve\n --port PORT The port to serve under\n --site-dir PATH Build directory for MkDocs (defaults to \"_site\")\n --base-url URL The base URL to prefix to autogenerated link inside\n the documentation.\nThe YAML Configuration allows you to define in one file all pages and the Python API objects they should contain. However, when you use Novella, each page will need to exist as a Markdown file. This has a few advantages:
- Easier to understand; The YAML
pagesconfiguration could be hard to reason about, while having an actual file for each page is much more human friendly and actually resembles the project structure for the static site generator in use. - 1-to-1 mapping; Each page in the final documentation is represented by a file in the source project, allowing things like the \"Edit URL\" generated by MkDocs to point to the actual page source rather than a 404 page.
- Mixing static and generated content; Placing generated API documentation where the
@pydoctag is used in the Markdown page allows you to put static documentation content around it.
Now, if you still want to generate Markdown files at build time, Pydoc-Markdown does not currently provide any functionality to do that; although some discussion around the topic is happening in #245. However, the Novella build script is just code, so if you really need it, you can generate the files there:
docs/build.novellatemplate \"mkdocs\"\n\ndef api_pages = {\n \"SomeClass\": \"my_module.SomeClass\",\n # ...\n}\n\naction \"mkdocs-update-config\" {\n site_name = \"My module\"\n profile = \"readthedocs\"\n update_with config -> {\n def items = []\n for title, package in api_pages.items():\n items.append({ title: 'api/{}.md'.format(package) })\n config['nav'].append({ 'API Documentation': items })\n }\n}\n\naction \"preprocess-markdown\" {\n use \"pydoc\"\n}\n\ndo\n name: \"generate-api-pages\"\n closure: {\n # Make sure that this action runs before the Markdown preprocessors.\n precedes \"preprocess-markdown\"\n }\n action: {\n for title, package in api_pages.items():\n def path = directory / 'content' / 'api' / (package + '.md')\n path.parent.mkdir(parents=True, exist_ok=True)\n path.write_text('---\\ntitle: {}\\n---\\n@pydoc {}\\n'.format(title, package))\n }\nPydoc-Markdown can be configured with using via a YAML file. By default, the CLI will look for a file called pydoc-markdown.yaml (or .yml) in the current working directory. (Note that the configuration is not read from file when using the -m,--module, -p,--package and other options that are intended for invoking Pydoc-Markdown without a configuration file).
Tip: The --bootstrap and --bootstrap-mkdocs options can be used to write a template configuration file.
If you use the YAML configuration, the configuration file is pre-processed with a YTT-like templating language (see YAML Preprocessing).
The configuration contains of four main sections:
loaders: A list of plugins that load API objects, for example from Python source files. The default configuration defines just apythonloader.processors: A list of plugins that process API objects to modify their docstrings (e.g. to adapt them from a documentation format to Markdown or to remove items that should not be rendered into the documentation). The default configuration defines thefilter,smartandcrossrefprocessors in that order.renderer: A plugin that produces the output files. The default configuration defines themarkdownrenderer (which by default will render a single file to stdout).hooks: Configuration for commands that will be executed before and after rendering.
loaders:\n- type: python\n search_path: [../src]\nrenderer:\n type: mkdocs\n pages:\n - title: API Documentation\n name: index\n contents:\n - school.*\n[[tool.pydoc-markdown.loaders]]\ntype = \"python\"\nsearch_path = [ \"../src\" ]\n\n[tool.pydoc-markdown.renderer]\ntype = \"mkdocs\"\n\n[[tool.pydoc-markdown.renderer.pages]]\ntitle = \"API Documentation\"\nname = \"index\"\ncontents = [ \"school.*\" ]\nNew in Pydoc-Markdown 3.3.0. See also pydoc_markdown.util.ytemplate
Pydoc-Markdown performs very basic pre-processing on the YAML configuration before it is deserialized. The format is similar to that of YTT, but supports only a subset of the features and logic is interpreted as actual Python code.
Supports preprocessing features:
defblocks to define a Python function (requires anendkeyword, encapsulating YAML code into the function definition is not supported)- Value substitution
Check out the Read the Docs/Hugo baseURL documentation for an example.
"},{"location":"usage/yaml/#loaders","title":"Loaders","text":"Loaders are configured in the $.loaders section of the Pydoc-Markdown configuration file. The key must be a list of loader definitions. Currently there is only the Python Loader.
Example:
loaders:\n- type: loadertype1\n key: value\n- type: loadertype2\nIf no loaders are specified, the Python loader is used by default.
"},{"location":"usage/yaml/#processors","title":"Processors","text":"Similar to the Loaders, the $.processors section expects a list of processor definitions. If no processors are defined, the filter, smart and crossref processors are used (in that order). Many processors do not have any additional options.
Example:
processors:\n- type: filter\n documented_only: false\n- type: smart\n- type: crossref\nThe $.renderer defines the renderer to use when running pydoc-markdown without arguments. Some renderers support the --server option, which allows a live-preview of the documentation. The default renderer is the Markdown renderer which will print the result to the terminal.
Other renderers may produce files on disk in a layout that conforms with the static site generator that they aim to support.
Example:
renderer:\n type: mkdocs\n pages:\n - title: API Documentation\n name: index\n contents:\n - school.*\nExample:
hooks:\n pre-render:\n - generate-changelog >docs/CHANGELOG.md\nAllows you to specify shell commands that will be execute before or after the render step.
Available keys
$.hooks.pre-render$.hooks.post-render
You can test the configuration of your loaders using the pydoc-markdown --dump option. Combine this with docpspec -m --dump-tree to get a full formatted list tree of all API objects that Pydoc-Markdown has discovered, after applying all processors. You can disable processors by adding the --without-processors function.
$ pydoc-markdown --dump | docspec -m --dump-tree\nmodule school._class\n| class Class\n| | data topic\n| | data teacher\nmodule school._person\n| class Person\n| | data name\n| | data age\nmodule school._pupil\n| class Pupil\n[ ... ]\nv4.8.2-3-g566847b (develop)","text":"Pydoc-Markdown is a tool to create Python API documentation in Markdown format. Instead of executing your Python code like so many other documentation tools, it parses it using docspec instead.
\u2192 Go to the Documentation \ud83d\udcd8
Table of Contents
- Installation \ud83d\udce6
- Features \ud83c\udf1f
- News \ud83d\udce2
- 4.7.0 (Undeprecating YAML configuration)
- 4.6.0 (Novella integration)
- Contributing to Pydoc-Markdown \ud83e\udd1d
- Questions / Need help? \ud83e\udd14
- Projects using Pydoc-Markdown \ud83d\udcda
You can install Pydoc-Markdown using Pipx:
$ pipx install pydoc-markdown\nIf you plan on using the Novella integration, you may want to install it as:
$ pipx install novella\n$ pipx inject novella pydoc-markdown[novella]\nYou need at least Python 3.7 to run Pydoc-Markdown. The Python version compatibility of the package you are looking to generate documentation for is irrelevant.
"},{"location":"#features","title":"Features \ud83c\udf1f","text":"- Understands multiple documentation styles (Sphinx, Google, Pydoc-Markdown specific) and converts them to properly formatted Markdown
- Can parse docstrings for variables thanks to docspec (
#:block before or string literal after the statement) - Generates links to other API objects per the documentation syntax (e.g.
#OtherClassfor the Pydoc-Markdown style) - Configure the output using a YAML file or
pyProject.toml, then you're only one command away to generate the documentation in Markdown format - Or use Novella to tightly integrate with static site generators like MkDocs and Hugo with with additional features such as Markdown pre-processing
Many users prefer the YAML configuration over the using Novella, which is why starting with 4.7.0, the YAML style configuration is officially un-deprecated and will continue to be supported.
"},{"location":"#460-novella-integration","title":"4.6.0 (Novella integration)","text":"Starting with 4.6.0, development focuses on integrating with Novella and use it as a replacement for tool-specific renderers thus far provided directly by Pydoc-Markdown (i.e. integrations with MkDocs, Hugo and Docusuraus). Such integrations are/will be provided by Novella instead.
With the Novella integration, you can now place generated API content in Markdown format inline with your existing Markdown documentation source files using @pydoc tags. Check out the Documentation for more information on how to use Pydoc-Markdown with Novella.
The old style of using Pydoc-Markdown with a YAML or PyProject configuration to generate files and kick off the build is now deprecated but will be maintained for the foreseeable future (at least until the next major version bump). It is strongly recommended to migrate your existing projects to using the Novella build backend.
"},{"location":"#contributing-to-pydoc-markdown","title":"Contributing to Pydoc-Markdown \ud83e\udd1d","text":"All contributions are welcome! Check out the Contribution Guidelines.
"},{"location":"#questions-need-help","title":"Questions / Need help? \ud83e\udd14","text":"Feel free to open a topic on GitHub Discussions!
"},{"location":"#projects-using-pydoc-markdown","title":"Projects using Pydoc-Markdown \ud83d\udcda","text":"An incomplete list of projects that use Pydoc-Markdown to generate their API documentation. Feel free to open a pull request to add your project to this list!
- CosmPy
- haystack by deepset
- tensorchord/envd
- tqdm
Contributions to Pydoc-Markdown are very welcome!
If you want to talk about a potential contribution before investing any time, please do create a new topic on GitHub Discussions.
"},{"location":"contributing/#pull-request-requirements","title":"Pull request requirements","text":"- Please look to adhere to the existing code style (2-space indendation, 120 character line length limit)
- Pull requests should contain at least one new changelog entry unless the change is trivial (see below for details)
Pydoc-Markdown uses Slam to manage changelogs. You should use the Slam CLI to add a new changelog entry, otherwise you need to manually generate a UUID-4.
$ slap changelog add -t <type> -d <changelog message> [--issue <issue_url>]\nAfter you create the pull request, GitHub Actions will take care of injecting the PR URL into the changelog entry.
"},{"location":"api/cli/","title":"Command-line interface","text":"Usage: pydoc-markdown [OPTIONS] [CONFIG]\n\n Pydoc-Markdown is a renderer for Python API documentation in Markdown\n format.\n\n With no arguments it will load the default configuration file. If the\n *config* argument is specified, it must be the name of a configuration file\n or a YAML formatted object for the configuration.\n\nOptions:\n --version Show the version and exit.\n --bootstrap [base|mkdocs|hugo|readthedocs|docusaurus]\n Create a Pydoc-Markdown configuration file\n in the current working directory.\n -v, --verbose Increase log verbosity.\n -q, --quiet Decrease the log verbosity.\n -m, --module MODULE The module to parse and generated API\n documentation for. Can be specified multiple\n times. Using this option will disable\n loading the default configuration file.\n -p, --package PACKAGE The package to parse and generated API\n documentation for including all sub-packages\n and -modules. Can be specified multiple\n times. Using this option will disable\n loading the default configuration file.\n -I, --search-path PATH A directory to use in the search for Python\n modules. Can be specified multiple times.\n Using this option will disable loading the\n default configuration file.\n --py2 / --py3 Switch between parsing Python 2 and Python 3\n code. The default is Python 3. Using --py2\n will enable parsing code that uses the\n \"print\" statement. This is equivalent of\n setting the print_function option of the\n \"python\" loader to False. Using this option\n will disable loading the default\n configuration file.\n --render-toc / --no-render-toc Enable/disable the rendering of the TOC in\n the \"markdown\" renderer.\n -s, --server Watch for file changes and re-render if\n needed and start the server for the\n configured renderer. This doesn't work for\n all renderers.\n -o, --open Open the browser after starting the server\n with -s,--server.\n --dump Dump the loaded modules in Docspec JSON\n format to stdout, after the processors.\n --with-processors / --without-processors\n Enable/disable processors. Only with --dump.\n --build Invoke a build after the Markdown files are\n produced. Note that some renderers may not\n support this option (e.g. the \"markdown\"\n renderer).\n --site-dir TEXT Set the output directory when using --build.\n --help Show this message and exit.\nVersion: pydoc-markdown, version 4.8.2
@dataclasses.dataclass\nclass PydocMarkdown()\n[view_source]
This object represents the main configuration for Pydoc-Markdown.
"},{"location":"api/pydoc_markdown/#loaders","title":"loaders","text":"A list of loader implementations that load docspec.Modules. Defaults to PythonLoader.
A list of processor implementations that modify docspec.Modules. Defaults to FilterProcessor, SmartProcessor and CrossrefProcessor.
A renderer for docspec.Modules. Defaults to MarkdownRenderer.
Hooks that can be executed at certain points in the pipeline. The commands are executed with the current SHELL.
def load_config(arg: t.Union[str, dict]) -> None\n[view_source]
Loads the configuration from a nested data structure or filename as specified per the data
argument. If a filename is specified, it may be a JSON, YAML or TOML file. If the name of the TOML file is pyproject.yoml, the configuration will be read from the [tool.pydoc-markdown] section.
Arguments:
data: A nested structure or the path to a configuration file.
def init(context: Context) -> None\n[view_source]
Initialize all plugins with the specified context. Cannot be called multiple times. If omitted, the plugins will be initialized with a default context before the load, process or render phase.
"},{"location":"api/pydoc_markdown/#load_modules","title":"load_modules","text":"def load_modules() -> t.List[docspec.Module]\n[view_source]
Loads modules via the loaders.
"},{"location":"api/pydoc_markdown/#process","title":"process","text":"def process(modules: t.List[docspec.Module]) -> None\n[view_source]
Process modules via the processors.
"},{"location":"api/pydoc_markdown/#render","title":"render","text":"def render(modules: t.List[docspec.Module], run_hooks: bool = True) -> None\n[view_source]
Render modules via the renderer.
"},{"location":"api/pydoc_markdown/interfaces/","title":"interfaces","text":"This module defines the interfaces that can to be implemented for Pydoc-Markdown to implement custom loaders for documentation data, processors or renderers.
"},{"location":"api/pydoc_markdown/interfaces/#class-context","title":"Class Context","text":"class Context()\n[view_source]
Context data that is passed to plugins when they are loaded.
"},{"location":"api/pydoc_markdown/interfaces/#class-loader","title":"Class Loader","text":"@Union(\n [\n \"!pydoc_markdown.interfaces.Loader\",\n \"<import>\",\n ],\n style=Union.FLAT,\n)\nclass Loader(PluginBase)\n[view_source]
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.
"},{"location":"api/pydoc_markdown/interfaces/#class-resolver","title":"Class Resolver","text":"class Resolver(abc.ABC)\n[view_source]
A resolver can be used by a Processor to replace cross references with a hyperlink.
"},{"location":"api/pydoc_markdown/interfaces/#class-resolverv2","title":"Class ResolverV2","text":"class ResolverV2(abc.ABC)\n[view_source]
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.
@Union(\n [\n \"!pydoc_markdown.interfaces.Processor\",\n \"<import>\",\n ],\n style=Union.FLAT,\n)\nclass Processor(PluginBase)\n[view_source]
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.
@Union(\n [\n \"!pydoc_markdown.interfaces.Renderer\",\n \"<import>\",\n ],\n style=Union.FLAT,\n)\nclass Renderer(PluginBase)\n[view_source]
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.
"},{"location":"api/pydoc_markdown/interfaces/#class-singlepagerenderer","title":"Class SinglePageRenderer","text":"class SinglePageRenderer(PluginBase)\n[view_source]
Interface for rendering a single page.
"},{"location":"api/pydoc_markdown/interfaces/#class-singleobjectrenderer","title":"Class SingleObjectRenderer","text":"class SingleObjectRenderer(PluginBase)\n[view_source]
Interface for rendering a single docspec.ApiObject.
class Server(abc.ABC)\n[view_source]
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.
def reload_server(process: subprocess.Popen) -> subprocess.Popen\n[view_source]
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(abc.ABC)\n[view_source]
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.
"},{"location":"api/pydoc_markdown/interfaces/#build","title":"build","text":"@abc.abstractmethod\ndef build(site_dir: str) -> None\n[view_source]
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.
"},{"location":"api/pydoc_markdown/interfaces/#class-sourcelinker","title":"Class SourceLinker","text":"@Union(\n [\n \"!pydoc_markdown.interfaces.SourceLinker\",\n \"<import>\",\n ],\n style=Union.FLAT,\n)\nclass SourceLinker(PluginBase)\n[view_source]
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.
"},{"location":"api/pydoc_markdown/loaders/","title":"pydoc_markdown.contrib.loaders.python","text":""},{"location":"api/pydoc_markdown/loaders/#class-pythonloader","title":"Class PythonLoader","text":"@dataclasses.dataclass\nclass PythonLoader(Loader)\n[view_source]
This implementation of the Loader interface parses Python modules and packages using docspec_python. See the options below to control which modules and packages are being loaded and how to configure the parser.
With no modules or packages set, the PythonLoader will discover available modules in the current and src/ directory.
lib2to3 Quirks
Pydoc-Markdown doesn't execute your Python code but instead relies on the lib2to3 parser. This means it also inherits any quirks of lib2to3.
List of known quirks
- A function argument in Python 3 cannot be called
printeven though it is legal syntax
A list of package names that this loader will search for and then parse, including all sub-packages and modules.
"},{"location":"api/pydoc_markdown/loaders/#search_path","title":"search_path","text":"The module search path. If not specified, the current sys.path is used instead. If any of the elements contain a * (star) symbol, it will be expanded with sys.path.
List of modules to ignore when using module discovery on the search_path.
"},{"location":"api/pydoc_markdown/loaders/#parser","title":"parser","text":"Options for the Python parser.
"},{"location":"api/pydoc_markdown/loaders/#encoding","title":"encoding","text":"The encoding to use when reading the Python source files.
Changed in 4.7.0: Default changed from None (system default encoding) to \"utf-8\".
Module: pydoc_markdown.contrib.processors.crossref
@dataclasses.dataclass\nclass CrossrefProcessor(Processor)\n[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)\nYou can rename a ref like `this`~PydocmdProcessor\nAnd you can append to the ref name like this: [PydocmdProcessors](#pydoc:pydoc_markdown.contrib.processors.pydocmd.PydocmdProcessor)\nRenders 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:\n - type: crossref\nIf 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
@dataclasses.dataclass\nclass FilterProcessor(Processor)\n[view_source]
The filter processor removes module and class members based on certain criteria.
Example configuration:
- type: filter\n expression: not name.startswith('_') and default()\n documented_only: false\nA 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
Keep only API objects that have docstrings. Default: true
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 members (e.g.__path__, __annotations__, __name__ and __all__). Default: true
Do not filter docspec.Module objects. Default: true
Skip modules with no content. Default: false.
Module: pydoc_markdown.contrib.processors.google
@dataclasses.dataclass\nclass GoogleProcessor(Processor)\n[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:\n module_level_variable1 (int): Module level variables may be documented in\n either the ``Attributes`` section of the module docstring, or in an\n inline docstring immediately following the variable.\n\n Either form is acceptable, but the two should not be mixed. Choose\n one convention to document module level variables and be consistent\n with it.\n\nTodo:\n * For module TODOs\n * You have to also use ``sphinx.ext.todo`` extension\nRenders as:
Attributes:
module_level_variable1int - Module level variables may be documented in either theAttributessection 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.todoextension
Module: pydoc_markdown.contrib.processors.pydocmd
@dataclasses.dataclass\nclass PydocmdProcessor(Processor)\n[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\n\narg1 (int): The first argument.\nkwargs (dict): Keyword arguments.\n\n# Raises\nRuntimeError: If something bad happens.\nValueError: If an invalid argument is specified.\n\n# Returns\nA value.\nRenders 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
@dataclasses.dataclass\nclass SmartProcessor(Processor)\n[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
@dataclasses.dataclass\nclass SphinxProcessor(Processor)\n[view_source]
This processor parses ReST/Sphinx-style function documentation and converts it into
Markdown syntax.
Example:
**Arguments**:\n\n- `arg1`: This is the first argument.\n- `arg1`: This is the first argument.\n\n**Raises**:\n\n- `ValueError`: If *arg1* is a bad value.\n- `ValueError`: If *arg1* is a bad value.\n\n**Returns**:\n\nAn `int` that represents an interesting value.\nRenders as:
"},{"location":"api/pydoc_markdown/renderers/docusaurus/","title":"docusaurus","text":""},{"location":"api/pydoc_markdown/renderers/docusaurus/#class-customizedmarkdownrenderer","title":"Class CustomizedMarkdownRenderer","text":"@dataclasses.dataclass\nclass CustomizedMarkdownRenderer(MarkdownRenderer)\n[view_source]
We override some defaults in this subclass.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#insert_header_anchors","title":"insert_header_anchors","text":"Disabled because Docusaurus supports this automatically.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#escape_html_in_docstring","title":"escape_html_in_docstring","text":"Escape html in docstring, otherwise it could lead to invalid html.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#render_module_header_template","title":"render_module_header_template","text":"Conforms to Docusaurus header format.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#class-docusaurusrenderer","title":"Class DocusaurusRenderer","text":"@dataclasses.dataclass\nclass DocusaurusRenderer(Renderer)\n[view_source]
Produces Markdown files and a sidebar.json file for use in a Docusaurus v2 websites. It creates files in a fixed layout that reflects the structure of the documented packages. The files will be rendered into the directory specified with the docs_base_path option.
Check out the complete Docusaurus example on GitHub.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#options","title":"Options","text":""},{"location":"api/pydoc_markdown/renderers/docusaurus/#markdown","title":"markdown","text":"The MarkdownRenderer configuration.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#docs_base_path","title":"docs_base_path","text":"The path where the docusaurus docs content is. Defaults \"docs\" folder.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#relative_output_path","title":"relative_output_path","text":"The output path inside the docs_base_path folder, used to output the module reference.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#relative_sidebar_path","title":"relative_sidebar_path","text":"The sidebar path inside the docs_base_path folder, used to output the sidebar for the module reference.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#sidebar_top_level_label","title":"sidebar_top_level_label","text":"The top-level label in the sidebar. Default to 'Reference'. Can be set to null to remove the sidebar top-level all together. This option assumes that there is only one top-level module.
"},{"location":"api/pydoc_markdown/renderers/docusaurus/#sidebar_top_level_module_label","title":"sidebar_top_level_module_label","text":"The top-level module label in the sidebar. Default to null, meaning that the actual module name will be used. This option assumes that there is only one top-level module.
"},{"location":"api/pydoc_markdown/renderers/hugo/","title":"hugo","text":""},{"location":"api/pydoc_markdown/renderers/hugo/#class-hugopage","title":"Class HugoPage","text":"@dataclasses.dataclass\nclass HugoPage(GenericPage[\"HugoPage\"])\n[view_source]
A subclass of {@link pydoc:pydoc_markdown.util.pages.Page} which adds Hugo-specific overrides.
"},{"location":"api/pydoc_markdown/renderers/hugo/#options","title":"Options","text":""},{"location":"api/pydoc_markdown/renderers/hugo/#preamble","title":"preamble","text":"The Hugo preamble of the page. This is merged with the HugoRenderer.default_preamble.
"},{"location":"api/pydoc_markdown/renderers/hugo/#directory","title":"directory","text":"Override the directory that this page is rendered into (relative to the content directory). Defaults to null.
@dataclasses.dataclass\nclass HugoConfig()\n[view_source]
Represents the Hugo configuration file that is rendered into the build directory.
"},{"location":"api/pydoc_markdown/renderers/hugo/#options_1","title":"Options","text":""},{"location":"api/pydoc_markdown/renderers/hugo/#title","title":"title","text":"Title of the site. This is a mandatory field.
"},{"location":"api/pydoc_markdown/renderers/hugo/#theme","title":"theme","text":"The theme of the site. This is a mandatory field. It must be a string, a HugoThemePath or a HugoThemeGitUrl object. Examples:
theme: antarctica\ntheme: {clone_url: \"https://github.com/alex-shpak/hugo-book.git\"}\ntheme: docs/hugo-theme/\nBase URL.
"},{"location":"api/pydoc_markdown/renderers/hugo/#serverurl","title":"serverURL","text":"Server URL. Default: 127.0.0.1 aka localhost
Server Port. Default: 1313
Language code. Default: en-us
@dataclasses.dataclass\nclass HugoRenderer(Renderer, Server, Builder)\n[view_source]
A renderer that produces Markdown files compatible with Hugo. The --bootstrap hugo option can be used to create a Pydoc-Markdown configuration file with the Hugo template.
- Adds a YAML preamble to every generated Markdown file.
- Produces files in a layout suitable for Hugo (e.g.
_index.mdfiles). - Produces a
config.yamlif config is not set tonull. - Can be used with the Pydoc-Markdown
--serveroption to live-preview the generated docs. - Downloads a suitable Hugo binary from Github if Hugo is not already installed (see get_hugo).
Example configuration:
renderer:\n type: hugo\n config:\n title: My Project\n theme: {clone_url: \"https://github.com/alex-shpak/hugo-book.git\"}\n # The \"book\" theme only renders pages in \"content/docs\" into the nav.\n content_directory: content/docs\n default_preamble: {menu: main}\n pages:\n - title: Home\n name: index\n source: README.md\n - title: API Documentation\n contents:\n - '*'\nThe directory where all generated files are placed. Default: build/docs
The directory inside the build directory where the generated pages are written to. Default: content
Clean up files that were previously generated by the renderer before the next render pass. Defaults to True.
The pages to render.
"},{"location":"api/pydoc_markdown/renderers/hugo/#default_preamble","title":"default_preamble","text":"The default Hugo preamble that is applied to every page. Example:
default_preamble:\n menu: main\nThe MarkdownRenderer configuration.
"},{"location":"api/pydoc_markdown/renderers/hugo/#config","title":"config","text":"The contents of the Hugo config.toml file as YAML. This can be set to null in order to not produce the config.toml file in the build_directory. Must be deserializable into a HugoConfig.
Options for when the Hugo binary is not present and should be downloaded automatically. Example:
get_hugo:\n enabled: true\n version: '0.71'\n extended: true\ndef install_hugo(to: str,\n version: str | None = None,\n extended: bool = True) -> None\n[view_source]
Downloads the latest release of Hugo from Github
and places it at the path specified by to. This will install the extended version if it is available and extended is set to True.
Arguments:
to: The file to write the Hugo binary to.version: The Hugo version to get. If not specified, the latest release will be used.extended: Whether to download the \"Hugo extended\" version. Defaults to True.
def get_github_releases(repo: str) -> t.Generator[dict, None, None]\n[view_source]
Returns an iterator for all releases of a Github repository.
"},{"location":"api/pydoc_markdown/renderers/hugo/#parse_links_header","title":"parse_links_header","text":"def parse_links_header(link_header: str) -> t.Dict[str, str]\n[view_source]
Parses the Link HTTP header and returns a map of the links. Logic from PageLinks.java.
at any point on future Pydoc-Markdown versions.
"},{"location":"api/pydoc_markdown/renderers/jinja2/#class-renderblock","title":"Class RenderBlock","text":"@D.dataclass\nclass RenderBlock()\n[view_source]
"},{"location":"api/pydoc_markdown/renderers/jinja2/#template","title":"template","text":"The path to the Jinja2 template that is used to render the output files.
"},{"location":"api/pydoc_markdown/renderers/jinja2/#produces","title":"produces","text":"A mapping for filename (without suffix) to a list of Module selectors.
"},{"location":"api/pydoc_markdown/renderers/jinja2/#jinja2_environment_settings","title":"jinja2_environment_settings","text":"Settings for the Jinja2 Environment.
"},{"location":"api/pydoc_markdown/renderers/jinja2/#class-jinja2renderer","title":"Class Jinja2Renderer","text":"@D.dataclass\nclass Jinja2Renderer(Renderer)\n[view_source]
"},{"location":"api/pydoc_markdown/renderers/jinja2/#renders","title":"renders","text":"Render instructions.
"},{"location":"api/pydoc_markdown/renderers/jinja2/#build_directory","title":"build_directory","text":"Build directory where all the files are produced.
"},{"location":"api/pydoc_markdown/renderers/markdown/","title":"markdown","text":""},{"location":"api/pydoc_markdown/renderers/markdown/#class-markdownrenderer","title":"Class MarkdownRenderer","text":"@dataclasses.dataclass\nclass MarkdownRenderer(Renderer, SinglePageRenderer, SingleObjectRenderer)\n[view_source]
Produces Markdown files. This renderer is often used by other renderers, such as MkdocsRenderer and HugoRenderer. It provides a wide variety of options to customize the generated Markdown files.
"},{"location":"api/pydoc_markdown/renderers/markdown/#options","title":"Options","text":""},{"location":"api/pydoc_markdown/renderers/markdown/#filename","title":"filename","text":"The name of the file to render to. If no file is specified, it will render to stdout.
"},{"location":"api/pydoc_markdown/renderers/markdown/#encoding","title":"encoding","text":"The encoding of the output file. This is ignored when rendering to stdout.
"},{"location":"api/pydoc_markdown/renderers/markdown/#insert_header_anchors","title":"insert_header_anchors","text":"If enabled, inserts anchors before Markdown headers to ensure that links to the header work. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#html_headers","title":"html_headers","text":"Generate HTML headers instead of Mearkdown headers. This is disabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#code_headers","title":"code_headers","text":"Render names in headers as code (using backticks or <code> tags, depending on html_headers). This is enabled by default.
Generate descriptive class titles by adding the word \"Objects\" if set to True. Otherwise, it can be a string that is appended or prepended (appended if the string begins with $). the class name. This is enabled by default.
Generate descriptivie module titles by adding the word \"Module\" before the module name. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#add_module_prefix","title":"add_module_prefix","text":"Add the module name as a prefix to class & method names. This module name is also rendered as code if code_headers is enabled. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#add_method_class_prefix","title":"add_method_class_prefix","text":"Add the class name as a prefix to method names. This class name is also rendered as code if code_headers is enabled. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#add_member_class_prefix","title":"add_member_class_prefix","text":"Add the class name as a prefix to member names. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#add_full_prefix","title":"add_full_prefix","text":"Add the full module name as a prefix to the title of the header. This is disabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#sub_prefix","title":"sub_prefix","text":"If add_full_prefix is enabled, this will result in the prefix to be wrapped in a <sub> tag.
Render the definition of data members as a code block. This is disabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#data_expression_maxlength","title":"data_expression_maxlength","text":"Max length of expressions. If this limit is exceeded, the remaining characters will be replaced with three dots. This is set to 100 by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#classdef_code_block","title":"classdef_code_block","text":"Render the class signature as a code block. This includes the \"class\" keyword, the class name and its bases. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#classdef_with_decorators","title":"classdef_with_decorators","text":"Render decorators before class definitions.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_python_help_style","title":"signature_python_help_style","text":"Render classdef and function signature blocks in the Python help() style.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_code_block","title":"signature_code_block","text":"Render the function signature as a code block. This includes the \"def\" keyword, the function name and its arguments. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_in_header","title":"signature_in_header","text":"Render the function signature in the header. This is disabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_with_vertical_bar","title":"signature_with_vertical_bar","text":"Render the vertical bar '|' before function signature. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_with_def","title":"signature_with_def","text":"Include the \"def\" keyword in the function signature. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_class_prefix","title":"signature_class_prefix","text":"Render the class name in the code block for function signature. Note that this results in invalid Python syntax to be rendered. This is disabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#signature_with_decorators","title":"signature_with_decorators","text":"Render decorators before function definitions.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_typehint_in_data_header","title":"render_typehint_in_data_header","text":"Render type hints for data elements in the header.
"},{"location":"api/pydoc_markdown/renderers/markdown/#code_lang","title":"code_lang","text":"Add the string \"python\" after the backticks for code blocks. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_page_title","title":"render_page_title","text":"Render title of page at the beginning of the file.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_toc","title":"render_toc","text":"Render a table of contents at the beginning of the file.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_toc_title","title":"render_toc_title","text":"The title of the \"Table of Contents\" header.
"},{"location":"api/pydoc_markdown/renderers/markdown/#toc_maxdepth","title":"toc_maxdepth","text":"The maximum depth of the table of contents. Defaults to 2.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_module_header","title":"render_module_header","text":"Render module headers. This is enabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_module_header_template","title":"render_module_header_template","text":"Custom template for module header.
"},{"location":"api/pydoc_markdown/renderers/markdown/#docstrings_as_blockquote","title":"docstrings_as_blockquote","text":"Render docstrings as blockquotes. This is disabled by default.
"},{"location":"api/pydoc_markdown/renderers/markdown/#use_fixed_header_levels","title":"use_fixed_header_levels","text":"Use a fixed header level for every kind of API object. The individual levels can be defined with header_level_by_type.
"},{"location":"api/pydoc_markdown/renderers/markdown/#header_level_by_type","title":"header_level_by_type","text":"Fixed header levels by API object type.
"},{"location":"api/pydoc_markdown/renderers/markdown/#source_linker","title":"source_linker","text":"A plugin that implements the SourceLinker interface to provide links to the source code of API objects. If this field is specified, the renderer will place links to the source code in the generated Markdown files.
"},{"location":"api/pydoc_markdown/renderers/markdown/#source_format","title":"source_format","text":"Allows you to override how the \"view source\" link is rendered into the Markdown file if a source_linker is configured. The default is [[view_source]]({url}).
Escape html in docstring. Default to False.
"},{"location":"api/pydoc_markdown/renderers/markdown/#render_novella_anchors","title":"render_novella_anchors","text":"Render Novella @anchor tags before headings.
Format code rendered into Markdown code blocks with YAPF.
"},{"location":"api/pydoc_markdown/renderers/markdown/#format_code_style","title":"format_code_style","text":"The style to format code as. This can be a YAPF builtin style name or point to a file relative to the context directory (usually the working directory).
"},{"location":"api/pydoc_markdown/renderers/markdown/#get_resolver","title":"get_resolver","text":"def get_resolver(modules: t.List[docspec.Module]) -> t.Optional[Resolver]\n[view_source]
Returns a simple Resolver implementation. Finds cross-references in the same file.
"},{"location":"api/pydoc_markdown/renderers/markdown/#class-markdownreferenceresolver","title":"Class MarkdownReferenceResolver","text":"@dataclasses.dataclass\nclass MarkdownReferenceResolver(Resolver, ResolverV2)\n[view_source]
"},{"location":"api/pydoc_markdown/renderers/markdown/#resolve_reference","title":"resolve_reference","text":"def resolve_reference(suite: ApiSuite, scope: docspec.ApiObject,\n ref: str) -> t.Optional[docspec.ApiObject]\n[view_source]
Resolves the reference by searching in the members of scope or any of its parents.
"},{"location":"api/pydoc_markdown/renderers/mkdocs/","title":"mkdocs","text":""},{"location":"api/pydoc_markdown/renderers/mkdocs/#class-customizedmarkdownrenderer","title":"Class CustomizedMarkdownRenderer","text":"@dataclasses.dataclass\nclass CustomizedMarkdownRenderer(MarkdownRenderer)\n[view_source]
We override some defaults in this subclass.
"},{"location":"api/pydoc_markdown/renderers/mkdocs/#class-mkdocsrenderer","title":"Class MkdocsRenderer","text":"@dataclasses.dataclass\nclass MkdocsRenderer(Renderer, Server, Builder)\n[view_source]
Produces Markdown files in a layout compatible with [MkDocs][0] and can be used with the Pydoc-Markdown --server option for a live-preview. The --bootstrap mkdocs option can be used to create a Pydoc-Markdown configuration file with the MkDocs template.
Example configuration:
renderer:\n type: mkdocs\n pages:\n - title: Home\n name: index\n source: README.md\n - title: API Documentation\n contents:\n - '*'\n mkdocs_config:\n site_name: My Project\n theme: readthedocs\nThe output directory for the generated Markdown files. Defaults to build/docs.
Name of the content directory (inside the output_directory). Defaults to \"content\".
"},{"location":"api/pydoc_markdown/renderers/mkdocs/#clean_render","title":"clean_render","text":"Remove files generated in a previous pass by the Mkdocs renderer before rendering again. Defaults to True.
Markdown renderer settings.
"},{"location":"api/pydoc_markdown/renderers/mkdocs/#site_name","title":"site_name","text":"The name of the site. This will be carried into the site_name key of the mkdocs_config.
Arbitrary configuration values that will be rendered to an mkdocs.yml file.
Port for the Mkdocs server when using the pydoc-markdown --server option. Defaults to 8000. Can be set with the MKDOCS_PORT environment variable:
$ MKDOCS_PORT=8383 pydoc-markdown -so\nbaseURL","text":"When using Hugo, usually you want to set the baseURL configuration so that it can generated permalinks properly. If you are building on Read the Docs, chances are that you will have multiple versions of the documentation, which all require a different baseURL.
Pydoc-Markdown configuration files are pre-processed with a YTT-like templating language.
#@ def base_url():\n#@ if env.READTHEDOCS:\n#@ return \"https://pydoc-markdown.readthedocs.io/en/\" + env.READTHEDOCS_VERSION + \"/\"\n#@ else:\n#@ return None\n#@ end\n\nrenderer:\n type: hugo\n config:\n baseURL: #@ base_url()\nUsing Pydoc-Markdown on readthedocs.org requires some \"hacking\" because natively it does not allow you to run any custom commands. Using readthedocs-custom-steps, you can hook into the call that RTD expects to generate the documentation using Sphinx/MkDocs and run your own commands instead.
Example
.readthedocs.ymlsetup.cfgpyproject.tomlversion: 2\nmkdocs: {} # tell readthedocs to use mkdocs\npython:\n version: 3.7\n install:\n - method: pip\n extra_requirements:\n - rtd\n[options.extras_require]\nrtd = readthedocs-custom-steps==0.6.2\n# ...\n\n[tool.readthedocs-custom-steps]\nscript = \"\"\"\nnovella --site-dir _site/html\n\"\"\"\nIf you only want to use Pydoc-Markdown to generate Markdown from Python code, but not use it for anything else (such as interfacing with a static site generator), you can of course do that. You can make use of the Class PythonLoader and Class MarkdownRenderer, or more conveniently the Class PydocMarkdown APIs, or use the CLI.
"},{"location":"usage/cli-and-api/#cli-example","title":"CLI Example","text":"The Pydoc-Markdown CLI accepts some options that can modify the default configuration (i.e. the Python loader and Markdown renderer) and write the generated Markdown to stdout.
pydoc-markdown -I src -m package_name.module_name --render-toc > module_name.md\nYou can also supply a YAML configuration as a positional argument that will be treated the same way as if it was loaded from a pydoc-markdown.yml file.
pydoc-markdown -m my_module '{\n renderer: {\n type: markdown,\n descriptive_class_title: false,\n render_toc: true\n }\n }' > my_module.md\nfrom pydoc_markdown.interfaces import Context\nfrom pydoc_markdown.contrib.loaders.python import PythonLoader\nfrom pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer\n\ncontext = Context(directory='.')\nloader = PythonLoader(search_path=['src'])\nrenderer = MarkdownRenderer(render_module_header=False)\n\nloader.init(context)\nrenderer.init(context)\n\nmodules = loader.load()\nprint(renderer.render_to_string(modules))\nNote
This does not include any filtering logic and will just render every member in your Python code.
from pydoc_markdown import PydocMarkdown\nfrom pydoc_markdown.contrib.loaders.python import PythonLoader\nfrom pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer\n\nsession = PydocMarkdown() # Preconfigured with a PythonLoader, FilterProcessor, CrossRefProcess, SmartProcessor and MarkdownRenderer\n\nassert isinstance(session.loaders[0], PythonLoader)\nsession.loaders[0].search_path = [\"src\"]\n\nassert isinstance(session.renderer, MarkdownRenderer)\nsession.renderer.render_to_string(session.process(session.load_modules()))\nWhen using the Pydoc-Markdown integration with Novella to make use of its Markdown pre-processing capabilities, Pydoc-Markdown comes as a plugin that provides a @pydoc and @pylink tag to insert Markdown documentation generated by Pydoc-Markdown in the corresponding places of your documentation.
When using Pipx, the recommended installation method is to inject Pydoc-Markdown later:
$ pipx install novella\n$ pipx inject novella pydoc-markdown[novella]\nIf you manage the environment yourself, it's sufficient to install Pydoc-Markdown with the novella extra.
$ pip install pydoc-markdown[novella]\nA Novella build is configured using a build.novella script. In most cases you want to rely on a template provided by Novella, such as the MkDocs template. Check out the Novella documentation to find what types of templates are available here.
template \"mkdocs\" {\n content_directory = \"content\"\n}\n\naction \"preprocess-markdown\" {\n use \"pydoc\"\n}\nWhat is happening here?
- The
mkdocspipeline template is applied. Thecontent_directoryis the directory that contains your MkDocs source files. It will be copied to the temporary build location alongside themkdocs.ymlfile. Note that yourbuild.novellascript should sit next two these files.
Note: You should have mkdocs on your PATH and it should have the mkdocs-material theme installed (the default theme that Novella will apply if you don't specify a different one in your mkdocs.yml file or in build.novella).
- The
preprocess-markdownaction that is one of the actions created by the template is retrieved and configured further. We instruct it to make use of the\"pydoc\"plugin, which is implemented by Pydoc-Markdown and provides the@pydocand{@link pydoc:}tags.
Note
-
The
content/directory is the default so it does not need to be set explicitly and it is sufficient to writetemplate \"mkdocs\"(without an empty configuration block). -
The
mkdocstemplate will apply a default configuration delivered with Novella to your MkDocs configuration. If you don't want this, you can configure the\"mkdocs-update-config\"action to disable this. Note that you can also have no MkDocs configuration file and the template will create a default file for you. -
The
pydoctag is implemented in {@link pydoc:pydoc_markdown.novella.preprocessor.PydocTagPreprocessor}. Look it up to understand how it can be configured further. -
The
pydoctag processor applies a heuristic to populate the default search path for your Python source code. If the directory in which the build is executed is calleddocsordocumentation, it will default to[ \"../src\", \"..\" ], otherwise it will default to[ \"src\", \".\" ].
For example, the @cat tag is useful to inject the content of another file.
# Welcome to my Project documentation!\n\n@cat ../../readme.md :with slice_lines = \"2:\"\nThe @pydoc tag is the piece provided by Pydoc-Markdown itself. It uses the Class MarkdownRenderer to generate Markdown formatted API documentation of the API object you specify.
# API Documentation\n\n@pydoc my_module.SomeClass\nChange into the docs/ directory where your build.novella script resides and invoke the Novella CLI. The MkDocs template exposes some command-line arguments that you can pass through the CLI, one of which is the --serve option that runs MkDocs in the server mode instead of building the documentation and writing it to disk.
usage: novella [--version] [-h] [-i TEMPLATE] [-c PATH] [-d DIRECTORY]\n [-b PATH] [-r] [--dot] [--intercept ACTION] [--serve]\n [--port PORT] [--site-dir PATH] [--base-url URL]\n\noptions:\n --version show program's version number and exit\n -h, --help Show this help output.\n -i TEMPLATE, --init TEMPLATE\n Create a `build.novella` file initialized from a\n template. Available templates are: \"mkdocs\", \"hugo\"\n -c PATH, --config-file PATH\n The configuration file to load. Can be a\n pyproject.toml in which case the code is looked up\n under the tool.novella.script key. (default: None)\n -d DIRECTORY, --directory DIRECTORY\n Switch to the specified directory before executing the\n configuration file.\n -b PATH, --build-directory PATH\n The build directory. If not specified, a temporary\n directory will be created.\n -r, --use-reloader Enable reloading, which will re-execute the pipeline\n if a watched file changes.\n --dot Produce a DotViz representation of the build graph.\n --intercept ACTION The name of an action to intercept and pause the\n execution, waiting for user input to continue. Useful\n for debugging intermediate steps of the build process.\n Currently, the action name must be matched exactly and\n actions can only be intercepted before they are run.\n If this option is provided, all possible intercept\n points are logged to the console.\n\ntemplate (mkdocs):\n --serve Use mkdocs serve\n --port PORT The port to serve under\n --site-dir PATH Build directory for MkDocs (defaults to \"_site\")\n --base-url URL The base URL to prefix to autogenerated link inside\n the documentation.\nThe YAML Configuration allows you to define in one file all pages and the Python API objects they should contain. However, when you use Novella, each page will need to exist as a Markdown file. This has a few advantages:
- Easier to understand; The YAML
pagesconfiguration could be hard to reason about, while having an actual file for each page is much more human friendly and actually resembles the project structure for the static site generator in use. - 1-to-1 mapping; Each page in the final documentation is represented by a file in the source project, allowing things like the \"Edit URL\" generated by MkDocs to point to the actual page source rather than a 404 page.
- Mixing static and generated content; Placing generated API documentation where the
@pydoctag is used in the Markdown page allows you to put static documentation content around it.
Now, if you still want to generate Markdown files at build time, Pydoc-Markdown does not currently provide any functionality to do that; although some discussion around the topic is happening in #245. However, the Novella build script is just code, so if you really need it, you can generate the files there:
docs/build.novellatemplate \"mkdocs\"\n\ndef api_pages = {\n \"SomeClass\": \"my_module.SomeClass\",\n # ...\n}\n\naction \"mkdocs-update-config\" {\n site_name = \"My module\"\n profile = \"readthedocs\"\n update_with config -> {\n def items = []\n for title, package in api_pages.items():\n items.append({ title: 'api/{}.md'.format(package) })\n config['nav'].append({ 'API Documentation': items })\n }\n}\n\naction \"preprocess-markdown\" {\n use \"pydoc\"\n}\n\ndo\n name: \"generate-api-pages\"\n closure: {\n # Make sure that this action runs before the Markdown preprocessors.\n precedes \"preprocess-markdown\"\n }\n action: {\n for title, package in api_pages.items():\n def path = directory / 'content' / 'api' / (package + '.md')\n path.parent.mkdir(parents=True, exist_ok=True)\n path.write_text('---\\ntitle: {}\\n---\\n@pydoc {}\\n'.format(title, package))\n }\nPydoc-Markdown can be configured with using via a YAML file. By default, the CLI will look for a file called pydoc-markdown.yaml (or .yml) in the current working directory. (Note that the configuration is not read from file when using the -m,--module, -p,--package and other options that are intended for invoking Pydoc-Markdown without a configuration file).
Tip: The --bootstrap and --bootstrap-mkdocs options can be used to write a template configuration file.
If you use the YAML configuration, the configuration file is pre-processed with a YTT-like templating language (see YAML Preprocessing).
The configuration contains of four main sections:
loaders: A list of plugins that load API objects, for example from Python source files. The default configuration defines just apythonloader.processors: A list of plugins that process API objects to modify their docstrings (e.g. to adapt them from a documentation format to Markdown or to remove items that should not be rendered into the documentation). The default configuration defines thefilter,smartandcrossrefprocessors in that order.renderer: A plugin that produces the output files. The default configuration defines themarkdownrenderer (which by default will render a single file to stdout).hooks: Configuration for commands that will be executed before and after rendering.
loaders:\n- type: python\n search_path: [../src]\nrenderer:\n type: mkdocs\n pages:\n - title: API Documentation\n name: index\n contents:\n - school.*\n[[tool.pydoc-markdown.loaders]]\ntype = \"python\"\nsearch_path = [ \"../src\" ]\n\n[tool.pydoc-markdown.renderer]\ntype = \"mkdocs\"\n\n[[tool.pydoc-markdown.renderer.pages]]\ntitle = \"API Documentation\"\nname = \"index\"\ncontents = [ \"school.*\" ]\nNew in Pydoc-Markdown 3.3.0. See also pydoc_markdown.util.ytemplate
Pydoc-Markdown performs very basic pre-processing on the YAML configuration before it is deserialized. The format is similar to that of YTT, but supports only a subset of the features and logic is interpreted as actual Python code.
Supports preprocessing features:
defblocks to define a Python function (requires anendkeyword, encapsulating YAML code into the function definition is not supported)- Value substitution
Check out the Read the Docs/Hugo baseURL documentation for an example.
"},{"location":"usage/yaml/#loaders","title":"Loaders","text":"Loaders are configured in the $.loaders section of the Pydoc-Markdown configuration file. The key must be a list of loader definitions. Currently there is only the Python Loader.
Example:
loaders:\n- type: loadertype1\n key: value\n- type: loadertype2\nIf no loaders are specified, the Python loader is used by default.
"},{"location":"usage/yaml/#processors","title":"Processors","text":"Similar to the Loaders, the $.processors section expects a list of processor definitions. If no processors are defined, the filter, smart and crossref processors are used (in that order). Many processors do not have any additional options.
Example:
processors:\n- type: filter\n documented_only: false\n- type: smart\n- type: crossref\nThe $.renderer defines the renderer to use when running pydoc-markdown without arguments. Some renderers support the --server option, which allows a live-preview of the documentation. The default renderer is the Markdown renderer which will print the result to the terminal.
Other renderers may produce files on disk in a layout that conforms with the static site generator that they aim to support.
Example:
renderer:\n type: mkdocs\n pages:\n - title: API Documentation\n name: index\n contents:\n - school.*\nExample:
hooks:\n pre-render:\n - generate-changelog >docs/CHANGELOG.md\nAllows you to specify shell commands that will be execute before or after the render step.
Available keys
$.hooks.pre-render$.hooks.post-render
You can test the configuration of your loaders using the pydoc-markdown --dump option. Combine this with docpspec -m --dump-tree to get a full formatted list tree of all API objects that Pydoc-Markdown has discovered, after applying all processors. You can disable processors by adding the --without-processors function.
$ pydoc-markdown --dump | docspec -m --dump-tree\nmodule school._class\n| class Class\n| | data topic\n| | data teacher\nmodule school._person\n| class Person\n| | data name\n| | data age\nmodule school._pupil\n| class Pupil\n[ ... ]\n