How do I make pdoc preserve whitespace?

Question

I'm trying to generate documentation using pdoc, where my docstrings look like this:

"""
I am a description of what a method does

:param param1: an integer
:param param2: a str
"""

I found this question: How to preserve line breaks when generating python docs using sphinx but the suggestion of prefixing each line with | did not work for me (it just showed up like this)

| :param param1: an integer | :param param2: a str

any ideas short of using \n at the end of every line?

Serles

What is pdoc? -- Also what happens if you move the first line up a line (e.g. """I am a ...)? That's the style recommended by PEP 257 so most tools that do docstring parsing should understand it. – Schleswigholstein

wiki.python.org/moin/DocumentationTools pdoc is a replacement for epydoc. Moving the first line up does nothing for the subsequent lines. – Serles

Ahh -- I see. Thanks. What happens if you try to tell pdoc to use reStructuredText the same way you would tell epydoc? e.g. add __docformat__ = 'restructuredtext en' at the top of the module? – Schleswigholstein

same result as before – Serles

Oh, Your documentation isn't in strict restructured text format... it'd be :param: an integer and :param: a string. And if that doesn't work (with the __docformat__ above, you could try the epydoc format: @type param1: int (newline) @param param1: Somthing about the integer here. -- Of course, you maybe already know this since you're trying to find a way to preserve newlines -- But I figured I'd point it out just in case. – Schleswigholstein

using @param param1: instead of :param param1: (which is what I was really doing, copied it wrong, will update) didn't make a difference – Serles

Maybe late, but IIRC pdoc does not use restructuredText; instead it use markdown. For the rest I am not sure I can help you – Pantoja

Answer 1

So, I've been having the same issue. Just figured it out. Pdoc uses markdown. You want to use a softbreak in mark down to tell it to create a newline while still keeping things grouped. A soft break is achieved by putting two trailing spaces at the end of the line you want to end with a new line.

You can check out this tutorial to see what I mean. http://www.markdowntutorial.com/lesson/7/

Additionally, be aware of what editor you are using. It might be removing trailing spaces! Trailing spaces removed on Python heredoc lines in PyCharm

"""
I am a description of what a method does

:param param1: an integer  <-- line ends right here with two spaces
:param param2: a str
"""

Traveler

@canhazbits haha thanks. I’ll take an upvote though! – Traveler