Custom renderes

[ariG23498]

What would be the best approach to provide a custom markdown renderer and use pydoc-markdown to customize the rendered pages according to my needs.

Parsing modules with docspec-python is a blessing. I would love to have a way to customise how my pages look after they are rendered.

[NiklasRosenstein]

Hey @ariG23498 ,

There is an interface for renderer plugins, and Pydoc-Markdown ships with a few default renderers: markdown, mkdocs, hugo and docusaurus. The markdown renderer is a standalone renderer, but is also used by the other three plugins. The other plugins do a lot of things aside from just rendering the files: they also determine the folder structure and output filenames, render a configuration file for the application that will turn Markdown into HTML, etc.

For example, if you want to use MkDocs but want to change how the Markdown files themselves are rendered, you can change the properties of the markdown renderer in the mkdocs renderer.

pydoc-markdown/pydoc-markdown/src/pydoc_markdown/contrib/renderers/mkdocs.py

Line 88 in 0b8a85d

markdown = Field(CustomizedMarkdownRenderer, default=CustomizedMarkdownRenderer)

like so:

renderer:
  type: mkdocs
  markdown:
    render_toc: true
    html_headers: true
    code_headers: true

If instead you are looking to produce a bunch of Markdown files in a specific format but also in a custom folder structure, there is not currently a native plugin that does just that. But you can take a look at the existing plugin's code to get started, and I'm also here to answer questions.

Cheers,

[ariG23498]

Thanks for the quick reply 👍
Having looked at the code, this seems like a excuisite repository and cheers to that!

My queries are twofold:

1. Is it possible to implement the interface for rendered plugins and then use the custom renderer in the configuration?
   Eg. Let's assume I make a custom_markdown.py that implements the renderer plugin. Later we could possibly do

renderer:
  type: custom_markdown

2. Is there a way we could change the template of the default renderes. Say I would like my decorators to not have the @ symbol in the documentation. I could do that by tweaking the markdown.py file. But that would not reflect in the pydoc-markdown package itself right?
   If I had a hold of the way the templating can be changed, it would be of great use to not only me but also a lot of people that would like to have custom documentation.

I did go through the docspec-python repository of yours. That is a gem in itself, but that helps me with parsing the source code file and returning the docspec objects. I would not want to make a doc generator on my own. Harnessing the powers of your repository and customising it would be a cherry on the cake. 😄

[songololo]

It would be really useful to have the option of specifying a filepath to a custom renderer (modelled on the existing Renderers).

[NiklasRosenstein]

Oh my, how has this slipped through the cracks until now. Sorry delaying the response almost up to a year 😿

Custom renderer

@ariG23498 To your first question

Is it possible to implement the interface for rendered plugins and then use the custom renderer in the configuration?
Eg. Let's assume I make a custom_markdown.py that implements the renderer plugin. Later we could possibly do

We're in Pydoc-Markdown 4.x now, but I think the same was also possible in Pydoc-Markdown 3x back in 2019. The steps needed to make this work are

1. Make sure the source file for your custom renderer can be found by the Python interpreter (for example by setting PYTHONPATH)
2. Reference your renderer in the Pydoc-Markdown configuration it's fully qualified name (i.e., module name + class name)

A small example

# myrenderer.py

import dataclasses
import docspec
import typing as t
from pathlib import Path
from pydoc_markdown.interfaces import Context, Renderer
from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer


@dataclasses.dataclass
class MyRenderer(Renderer):

  output_dir: str

  markdown: MarkdownRenderer = dataclasses.field(default_factory=MarkdownRenderer)

  def init(self, context: Context) -> None:
    self.markdown.init(context)

  def render(self, modules: t.List[docspec.Module]) -> None:
    Path(self.output_dir).mkdir(parents=True, exist_ok=True)
    for module in modules:
      path = Path(self.output_dir) / f'{module.name}.md'
      path.write_text(self.markdown.render_to_string([module]))

# pydoc-markdown.yaml

loaders:
  - type: python
    search_path: [ src ]
renderer:
  type: myrenderer.MyRenderer
  output_dir: generated

Now when you run pydoc-markdown, you need to make sure that myrenderer.py can be found. If it's in the same directory as where you're running the command from:

$ PYTHONPATH=. pydoc-markdown

@songololo I hope this answers your questions as well 🙂

Markdown template tweaks

To your second question,

Is there a way we could change the template of the default renderes. Say I would like my decorators to not have the @ symbol in the documentation. I could do that by tweaking the markdown.py file. But that would not reflect in the pydoc-markdown package itself right?
If I had a hold of the way the templating can be changed, it would be of great use to not only me but also a lot of people that would like to have custom documentation.

The particular renderers for Docusaurus, MkDocs and Hugo all use the MarkdownRenderer internally, which is exposed as a field named markdown. That means all of the configuration options provided by the markdown renderer are still configurable when using one of these tool-specific renderers.

Example

renderer:
  type: hugo
  markdown:
    source_linker:
      type: github
      repo: NiklasRosenstein/pydoc-markdown
  add_module_prefix: yes
  classdef_with_decorators: false

However, your particular question for not rendering the @ in the classdef/function signature is not configurable in the MarkdownRenderer right now. You are welcome to create a pull requests to make this configurable though!

pydoc-markdown/pydoc-markdown/src/pydoc_markdown/contrib/renderers/markdown.py

Lines 248 to 250 in 5baad1c

	def _format_decorations(self, decorations: t.List[docspec.Decoration]) -> t.Iterable[str]:
	for dec in decorations:
	yield '@{}{}\n'.format(dec.name, dec.args or '')

If you need more flexibility than this, Pydoc-Markdown 4.1.0 introduced an experimental Jinja2 renderer. However do note that as of right now, the Jinja2 renderer API and configuration is not stable.