search

NiklasRosenstein / pydoc-markdown

Create Python API documentation in Markdown format.
http://niklasrosenstein.github.io/pydoc-markdown/
Other
458 stars 102 forks source link

Markdown Admonitions in Docusaurus #184

Open jaydm26 opened 3 years ago

jaydm26 commented 3 years ago

Hello!

Currently, all keywords within the docstring of a Python code (e.g. Args, Returns, Warnings, Raises, Notes, etc.) are rendered as boldface text within the generated markdown file.

Since admonitions are supported in docusaurus, I was hoping for an addition of a feature to allow admonitions like Warnings to be rendered as true admonitions (like here).

NiklasRosenstein commented 3 years ago

hey @jaydm26 , could you give an example of what you would like to be able to write syntactically and what the expected rendered output would be in Markdown format? Is this specific to the Pydoc-Markdown documentation format, or Sphinx or Google?

jaydm26 commented 3 years ago

Sure! Consider the following within a docstring:

Caution: This function is unstable and can produce unexpected results.

What I was hoping to see when this gets converted to markdown is:

:::caution

This function is unstable and can produce unexpected results.

:::

The above is along the lines of admonitions that have been introduced in docusaurus v2.