6

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?

Community
  • 1
  • 1
Colleen
  • 23,899
  • 12
  • 45
  • 75
  • 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](https://www.python.org/dev/peps/pep-0257/) so most tools that do docstring parsing should understand it. – mgilson Sep 21 '15 at 20:46
  • https://wiki.python.org/moin/DocumentationTools pdoc is a replacement for epydoc. Moving the first line up does nothing for the subsequent lines. – Colleen Sep 21 '15 at 20:53
  • 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'`](http://epydoc.sourceforge.net/othermarkup.html) at the top of the module? – mgilson Sep 21 '15 at 20:56
  • same result as before – Colleen Sep 21 '15 at 21:27
  • 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. – mgilson Sep 21 '15 at 21:32
  • using `@param param1:` instead of `:param param1:` (which is what I was really doing, copied it wrong, will update) didn't make a difference – Colleen Sep 21 '15 at 22:24
  • Maybe late, but IIRC pdoc does not use restructuredText; instead it use markdown. For the rest I am not sure I can help you – Synxis Dec 22 '15 at 14:36

1 Answers1

8

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
"""
Maximilian Hils
  • 6,309
  • 3
  • 27
  • 46
bravosierra99
  • 1,331
  • 11
  • 23