Add Google style doc string support (original: What's good format for portray as docstring?)

[ki4070ma]

I use google style as docstring. But it doesn't look good when generating doc by portray.

Do I need to follow the same way on portray's doc? Or can I generate better doc with google docstring style somehow? This might be enhancement.

Not good

https://ki4070ma.github.io/python-client/reference/appium/webdriver/extensions/device_time/

Example

https://timothycrosley.github.io/portray/reference/portray/render/

• I can see bullet points

Google style as docstring

https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

[timothycrosley]

Hi @ki4070ma,

Right now only markdown formatting of doc strings is supported. I'm going to convert this into an enhancement request for GoogleDoc formatting support, and hopefully get to it soon.

Thanks!

~Timothy

[sambhav]

One of the major blockers to moving a lot of internal projects I maintain at my workplace to mkdocs (I currently use a combination of sphinx + napoleon + recommonmark to achieve this, but I miss the mkdocs theme) has been the inability to auto-generate docs from docstrings. I see that pdoc3 supports this, but I am also aware of the controversy behind that fork and the reason pdocs was created. It would be amazing if we could somehow implement Google style parsing in pdocs and in turn portray. Are there any active development plans on this enhancement?

If not I might take a shot at it later down the month.

[timothycrosley]

Currently, there is a desire to support this, but no direct work in progress. Any help in this area would be greatly appreciated!

[tristanlatr]

How funny!

I also looked for a replacement for pdoc3 after I've seen the discreet svastikas symbols in the footer of the website...

I'm currently porting the Sphinx napoleon extension to pydoctor, another documentation tool generator that I switched to.

May be my work can be slightly extended to give option to convert both to markdown and RST. Is it unthinkable ? Just trying to see if we can collectivise our coding efforts here... I think forking napoleon to process docstrings is the way to go because it's been massively used and it's pretty battle tested. But yeah.. it only speaks reStructuredText for now.

@mthuurne

[sanzoghenzo]

#69 should have fixed this, I forgot to refer to this issue in there...

[mthuurne]

Hi, I'm the current maintainer of pydoctor.

I'm currently porting the Sphinx napoleon extension to pydoctor, another documentation tool generator that I switched to.

May be my work can be slightly extended to give option to convert both to markdown and RST. Is it unthinkable ? Just trying to see if we can collectivise our coding efforts here... I think forking napoleon to process docstrings is the way to go because it's been massively used and it's pretty battle tested. But yeah.. it only speaks reStructuredText for now.

It would require separating the parsing code in napoleon's GoogleDocstring class from the code that generates output. Maybe an interface (abstract class or typing.Protocol) could define methods that handle parse events. Then pydoctor can implement that interface to generate RST or perhaps a docutils tree and other projects can implement it differently to output for example Markdown.

Looking at how pdocs solved it: if I understand correctly, it uses docstring_parser to parse the docstring into a simple DOM and then generates Markdown from that DOM using Mako templates. We could consider adopting docstring_parser in pydoctor. It would require adding epytext support to it, but that's not too large a task.

One concern I have is how complete the parsers in docstring_parser are. Looking at the code of the RST parser, it doesn't look like it supports more than the most essential features.

In any case, I think that the Python community as a whole benefits a lot from good documentation, so if there is anything we can do to help each other improve documentation tooling or specs/conventions, I'm interested.

[fsoubelet]

Hi all, is there any news on this? I am on the latest version of both portray and pdocs but the generated documentation is all over the place.