Docstrings using reST missing formatting.

[nimbusscale]

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? I didn't see this option in the docs, so if I missed it then I apologize.

For example, I have this function:

`def clear_evaluations(rule_name: str, region: str = None, session: boto3.Session = boto3.Session()) -> None:
"""Clears the evaluations for a specified config rule.

:param rule_name: Name of the config rule.
:param region: Region where the config rule is configured.
:param session: A boto3 session, can be used to facilitate using a cross-account
:return: None
"""`

But in the HTML docs it shows up as shown in this screenshot which is hard for a human to read:

I tried the Google style and that does come out formatted well, but all our docstrings are in reST given that is the default for PyCahrm. I don't care about bolding or any other format of the text, just want the carriage return preserved so it's human-readable.

Thanks for any guidance you can provide.

Additional info

• pdoc version:

$ pip freeze | grep pdoc pdoc3==0.8.4

[kernc]

Duplicate of #110.

ReST support, other than some explicitly listed directives, is non-existent. Text is interpreted as markdown.

---

Have tried to override default to_html() in your config.mako to something more no-op?

pdoc/pdoc/templates/html.mako

Lines 17 to 18 in cd84fb3

	def to_html(text):
	return _to_html(text, docformat=docformat, module=module, link=link, latex_math=latex_math)

# config.mako:

def to_html(text):
    return text.replace('\n', '<br>')

[nimbusscale]

I was able to follow the little breadcrumb kernc provided and I wanted to expand it for others that are looking to sort out the same issue.

It appears pdoc allows you to customize how things are rendered via some config files. These are discussed more here: https://pdoc3.github.io/pdoc/doc/pdoc/#custom-templates.

So what I did is I created a directory in my project that I called pdoc-templates and I copied the html.mako into that directory. I just got the file here: https://raw.githubusercontent.com/pdoc3/pdoc/master/pdoc/templates/html.mako

I then updated the to_html function to reflect what kenc suggested above. After the I ran the following command:

pdoc --html --force --template-dir pdoc-templates/ my_package

This caused the rendered template to treat the docstring as preformatted text. This broke all other rendering, which is fine for us, but markdown and such will not be rendered.

Kernc did reference config.mako, but linked to html.mako. I tried copying the config.mako to the pdoc-templates dir and added the to_html function to my copy of config.mako, but that didn't seem to make a difference. So I'm not sure if kernc wrote config.mako by mistake or I did something wrong, but I was able to get it working when updating html.mako.

[kernc]

I did mean config.mako. I was under the impression function overrides in config.mako are used preferentially. Apparently this is not the case. 😬