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.

https://github.com/NiklasRosenstein/pydoc-markdown/blob/0b8a85d84d063b5ce9a1fd73d88dda6a199d5583/pydoc-markdown/src/pydoc_markdown/contrib/renderers/mkdocs.py#L88

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 :+1: 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. :smile:

[songololo]

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