I'm looking for a way to generate a single Markdown (.md) file that includes all the file names, function definitions, and docstrings from my Python files. Ideally, this should traverse a directory recursively while respecting the .gitignore rules.

Does anyone know of a package that accomplishes this?

you are viewing a single comment's thread
view the rest of the comments

[–] jadelord@discuss.tchncs.de 2 points 1 month ago (5 children)

Sphinx's autodoc tool does gathering documentation and will traverse the whole package with the right config. It can read markdown with myst-parser. It provides HTML, TeX etc as output formats out of the box, however if you need markdown as output you many need an extension.

[–] why0y@lemmy.ml 2 points 1 month ago (3 children)

Would seriously love someone to rip down Sphinxdoc and put this baby to bed.

In my history of using docstrings, I've put maybe 20-40minutes of docs into a 200k+ codebase. It's super easy.

In my history of using Sphinx autodoc, I've spent about 5-10 hours fumbling with Makefiles, configs, and other nightmares and it still has the worst developer experience after about 8 years of using it.

[–] logging_strict@programming.dev 2 points 1 month ago (2 children)

For the Makefile and conf.py, it's a Ctrl+P job. tox.ini more Ctrl+P. Crap that goes into pyproject.toml Ctrl+P.

ETA ~20 mins including bathroom breaks and chatting with friends that randomly arrive at the cafe.

Then comes dealing with fixing up the URLs and references. That is the only time consuming bit.

Have posted links to packages i've written, can just go there and five finger discount the configuration files.

Howto autodoc, i'm not licensed to sell without a medical license. But there is a shot for that. ;-)

[–] why0y@lemmy.ml 2 points 1 month ago (1 children)

Will checkout your repos. Thanks for comment. It's been a breeze to write python and the docstrings are pretty great. I've had periods where everything just worked for Sphinx autodoc and then others where it's just broken for months. Thanks again

[–] logging_strict@programming.dev 2 points 1 month ago

If/when run into issues with Sphinx, 1st the project should be accessible online then message me with the URL and ask for help. I'm battle hardened; will conquer whatever Sphinx autodoc demons assails you.

This goes for everyone else as well. If have the Sphinx blues, don't whine about it, just ask for help.

Especially if your project is awe inspiring. Online read lots of complaining about writing documentation, but see it as just as important as the code or business model. Your documentation should not suck. Don't half ass it.

Also i'm really curious how autodoc stays broken (for months). Take that to mean, there are things that need to be learned. Not knowing those things Sphinx can be frustrating. For example, dealing with Type aliases and table of contents.

load more comments (1 replies)