21

The title says it all. What I imagine is to have docstrings for all of my modules, classes and functions and somehow nicely navigate the doc via github (wiki?). Also, the doc should be in sync with latest code meaning it should be updated/re-generated on push. Is that possible?

Linuxios
  • 34,849
  • 13
  • 91
  • 116
Giampaolo Rodolà
  • 12,488
  • 6
  • 68
  • 60
  • Sphinx is definitely it, although it uses restructuredText rather than Markdown. For Markdown, there is mkdocs, but that doesn't support docstrings. Although, I did start this experiment (which may be a bad idea): https://github.com/waylan/mddoc – Waylan Apr 15 '15 at 23:40
  • I had the same problem ([readme.md](https://github.com/matteoferla/mutagenesis)) and I do not believe there is a nice answer. I tried mkdocs —just polluted my folder— and [pydoc_markdown](https://github.com/NiklasRosenstein/pydoc-markdown), the top Google hit, which gave a fraction of the text pydoc gave. In the end I simply got the pydoc output and did a three or four search and replaced a few items. – Matteo Ferla Mar 25 '16 at 14:35
  • We've noticed that the Github per-repo wikis aren't tied to the main repo commits, meaning that if you want accurate per-commit documentation (so that any commit checked out has the right doc for it), the per-repo wiki is useless. – Alex North-Keys Aug 08 '16 at 08:39
  • Is it possible to show some minimal example of what you start with and the md you want to finish with? – stevec Nov 18 '20 at 23:52

2 Answers2

2

Just pipe the output of the generated docstring to a .md file.

Like this:

pydoc example_lib > example_lib.md .
Saurav Maheshkar
  • 183
  • 1
  • 11
Kevin Gray
  • 31
  • 5
0

Pydoc doesn't generate markdown, it generates an ad-hoc text markup that only occasionally by luck matches markdown. You would need to have an ad-hoc text to markdown converter, which will fail a lot, same as using the raw ad-hoc text as if it already were markdown.

MatthewMartin
  • 32,326
  • 33
  • 105
  • 164