How can I use both Sphinx and Pycco for Python documentation?

Question

I'd like to be able to use Sphinx for the main project documentation, so the docstrings must be in reStructuredText, but I'd also like to generate HTML for reading the inline comments in the style of Pycco, which uses Markdown.

Is there a tool or combination of tools that will allow me to do convert only the docstrings from reStructuredText to Markdown?

score 0 · Answer 1 · edited Jun 20 '20 at 09:12

0

A software called Pandoc may be the right tool. You can see the detail in the page through the hyperlink. I ever wanted to have try of it, but it needs Haskell runtime environment which is a little big, so I gave up.

edited Jun 20 '20 at 09:12

Community

1
1

answered Mar 13 '14 at 08:23

ChaosCosmos

109
8

Thank you, I looked into that but couldn't find an easy way of using it only on the docstrings. Of course, I could always write something that programmatically pulls all the docstrings, converts them with Pandoc, and puts them back—but then I'd be writing my own tool, which I was hoping someone else had already done. If this question doesn't turn up any answers, then I suppose I'll do it if I find the time `:)` – Will Mar 13 '14 at 15:50

score 0 · Answer 2 · answered Sep 13 '18 at 15:02

The pyment tool can convert docstrings to different formats. You could start with that, and then write a subclass of DocToolsBase to format docstrings the way you like.

See this question What is the standard Python docstring format? for more about python docstring conventions and tooling.

How can I use both Sphinx and Pycco for Python documentation?

2 Answers2