Convert NumPy-style docstring sections into Markdown. See https://numpydoc.readthedocs.io/en/latest/format.html for details. def rst(contents: str, source_file: pathlib.Path | None) -> str: View Source · 273def rst(contents: str, source_file: Path | None) -> str: 274 """ 275 Convert reStructuredText elements to Markdown.

If you look closely, you'll notice that docstrings are interpreted as Markdown. For example, `pdoc` is rendered as pdoc. Additionally, identifiers such as the type annotation for Dog.friends are automatically linked.

The assignments to __pdoc__ need to be placed where they'll be executed when the module is imported. For example, at the top level of a module or in the definition of a class. Currently, pure Markdown (with extensions), numpydoc, and Google-style docstrings formats are supported, along with ...

August 15, 2020 - I get that there is limited support for reST, but docstrings using that format seem to turn into a jumbled mess in the HTML documentation as the carriage returns are stripped out. Is there a way to just have the docs include the docstring as a preformatted text?

July 5, 2025 - Documentation is never complete without the ‘Example’ or ‘How to use’ section. To ensure that our documentation also includes this, don’t forget to add sample usage followed by the ‘Example’ tag in the docstrings of the methods. Refer this article to see how to add examples in various docstring formats.

Auto-generate API documentation for Python projects from docstrings in numpydoc, Google, or plain Markdown format.

June 3, 2018 - My feeling is that we should clearly cater for doctests and pre-formatted docstrings, and choose a more flexible markdown renderer that includes Github-style tables and the like. Equally, I feel we should clearly not include support for reStructuredText, which is way too large and complicated. I'm undecided about things like Google style and EpyText, which are intermediate. It's possible that we could use a Github-style type marker for this: """raw This is a pre-formatted docstring.

For example, at the top level of a module or in the definition of a class. Currently, pure Markdown (with [extensions]), [numpydoc], and [Google-style] docstrings formats are supported, along with some reST directives.

May 10, 2025 - Built as a successor to Epydoc, Pdoc uses introspection to extract documentation from source code docstrings and allows programmers to generate HTML documentation for chosen Python modules. It is thus functionally similar to Pydoc, Perldoc and Javadoc. It supports identifier cross-linking and Markdown for its doc string format...

February 21, 2020 - I note that pdoc3 supports pure Markdown (with extensions), numpydoc, and Google-style docstrings formats, and you have partial reStructuredText support (see #110). I do not see that you allow explicit declaration of which markup languag...

This module handles the conversion of docstring flavors to Markdown.

141 """ 142 self.modulename = modulename 143 self.qualname = qualname 144 self.obj = obj 145 self.taken_from = taken_from 146 147 @cached_property 148 def fullname(self) -> str: 149 """The full qualified name of this doc object, for example `pdoc.doc.Doc`.""" 150 # qualname is empty for modules 151 return f"{self.modulename}.{self.qualname}".rstrip(".") 152 153 @cached_property 154 def name(self) -> str: 155 """The name of this object. For top-level functions and classes, this is equal to the qualname attribute.""" 156 return self.fullname.split(".")[-1] 157 158 @cached_property 159 def docstring(self) -> str: 160 """ 161 The docstring for this object.

pdoc's main feature is a focus on simplicity: pdoc aims to do one thing and do it well. Documentation is plain Markdown. First-class support for type annotations and all other modern Python 3 features. Builtin web server with live reloading. Customizable HTML templates. Understands numpydoc and Google-style docstrings...

January 22, 2025 - I am a big fan of the markdown format for writing documentation. Don’t you use it often too for your Github Readme docs? The great thing about pdoc is that it allows seamless integration of markdown text inside your docstring.

October 17, 2020 - I have a project that uses "classic" style docstrings, that style/format gets sometimes called "Sphinx style" and sometimes "reST" style: """ Some text to describe what the function does. This can span several lines. :param param1: descr...

July 8, 2024 - Simplicity: PDoc is easy to set up and use, allowing you to generate documentation with just a few commands. Docstring Support: It supports both Google-style and NumPy-style docstrings, giving you flexibility in writing your documentation.

January 25, 2016 - Does (and how) pdoc support different established docstring styles (e.g. google style, numpy style, javadoc, reST)? Are there other "best practice" docstring conventions for formatting do...

December 3, 2020 - Pdoc is vastly simpler to use than Sphinx for small projects, with good HTML formatting. In distinction from Sphinx, pdoc does not parse RST docstrings, but Pdoc does allow the following docstring formats:

February 14, 2025 - There are many Docstrings formats available, but it is always better to use the formats which are easily recognized by the Docstring parser and also by fellow Data Scientists/programmers. There are no rules and regulations for selecting a Docstring format, but the consistency of choosing the same format over the project is necessary.