Skip to content

markdown

Class MarkdownRenderer

@dataclasses.dataclass
class MarkdownRenderer(Renderer, SinglePageRenderer, SingleObjectRenderer)

[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.

Options

filename

The name of the file to render to. If no file is specified, it will render to stdout.

encoding

The encoding of the output file. This is ignored when rendering to stdout.

insert_header_anchors

If enabled, inserts anchors before Markdown headers to ensure that links to the header work. This is enabled by default.

html_headers

Generate HTML headers instead of Mearkdown headers. This is disabled by default.

code_headers

Render names in headers as code (using backticks or <code> tags, depending on html_headers). This is enabled by default.

descriptive_class_title

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.

descriptive_module_title

Generate descriptivie module titles by adding the word "Module" before the module name. This is enabled by default.

add_module_prefix

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.

add_method_class_prefix

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.

add_member_class_prefix

Add the class name as a prefix to member names. This is enabled by default.

add_full_prefix

Add the full module name as a prefix to the title of the header. This is disabled by default.

sub_prefix

If add_full_prefix is enabled, this will result in the prefix to be wrapped in a <sub> tag.

data_code_block

Render the definition of data members as a code block. This is disabled by default.

data_expression_maxlength

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.

classdef_code_block

Render the class signature as a code block. This includes the "class" keyword, the class name and its bases. This is enabled by default.

classdef_with_decorators

Render decorators before class definitions.

signature_python_help_style

Render classdef and function signature blocks in the Python help() style.

signature_code_block

Render the function signature as a code block. This includes the "def" keyword, the function name and its arguments. This is enabled by default.

signature_in_header

Render the function signature in the header. This is disabled by default.

signature_with_vertical_bar

Render the vertical bar '|' before function signature. This is enabled by default.

signature_with_def

Include the "def" keyword in the function signature. This is enabled by default.

signature_class_prefix

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.

signature_with_decorators

Render decorators before function definitions.

render_typehint_in_data_header

Render type hints for data elements in the header.

code_lang

Add the string "python" after the backticks for code blocks. This is enabled by default.

render_page_title

Render title of page at the beginning of the file.

render_toc

Render a table of contents at the beginning of the file.

render_toc_title

The title of the "Table of Contents" header.

toc_maxdepth

The maximum depth of the table of contents. Defaults to 2.

render_module_header

Render module headers. This is enabled by default.

render_module_header_template

Custom template for module header.

docstrings_as_blockquote

Render docstrings as blockquotes. This is disabled by default.

use_fixed_header_levels

Use a fixed header level for every kind of API object. The individual levels can be defined with header_level_by_type.

header_level_by_type

Fixed header levels by API object type.

source_linker

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.

source_format

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

Escape html in docstring. Default to False.

render_novella_anchors

Render Novella @anchor tags before headings.

format_code

Format code rendered into Markdown code blocks with YAPF.

format_code_style

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).

get_resolver

def get_resolver(modules: t.List[docspec.Module]) -> t.Optional[Resolver]

[view_source]

Returns a simple Resolver implementation. Finds cross-references in the same file.

Class MarkdownReferenceResolver

@dataclasses.dataclass
class MarkdownReferenceResolver(Resolver, ResolverV2)

[view_source]

resolve_reference

def resolve_reference(suite: ApiSuite, scope: docspec.ApiObject,
                      ref: str) -> t.Optional[docspec.ApiObject]

[view_source]

Resolves the reference by searching in the members of scope or any of its parents.