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?

top 4 comments

sorted by: hot top controversial new old

[–] matthewdeanmartin@programming.dev 9 points 3 months ago

There are A LOT of these. I have had good experience with https://pypi.org/project/git2md

Says "Support for .gitignore, .globalignore and .mdignore for local projects: Automatically excludes files/directories specified in .gitignore, .globalignore or .mdignore."

If you don't find what you like, I've also found it easy to ask LLMs to just write a tool customized to my use case, usually when I need to somehow condense the code base to make it fit in the context.

[–] eager_eagle@lemmy.world 5 points 3 months ago

https://mkdocstrings.github.io/

[–] jadelord@discuss.tchncs.de 2 points 3 months ago (1 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.

[–] logging_strict@programming.dev 2 points 3 months ago* (last edited 3 months ago)

Just spent the last two weeks (no exaggeration) putting documentation together. Ensuring references resolve correctly is the time consuming bit.

extlinks, nitpick_ignore, autodoc_type_aliases, intersphinx_mapping, multiple extensions, and building inventories using sphobjinv, Table of contents using sphinx-external-toc-strict links to both ref and docs.

The table of contents supports both .md and .rst files. With the caveat that the initial file must be index.rst.

Having to relearn all this crap to do the same thing (e.g. mkdocs)? Would rather stick a fork in my eye.

Here is a sample TOC config file wreck _toc.yml from package wreck. Shows globs:, file:, url: links.

This one includes both .rst and .md strict TOC _toc.yml

Output is a user manual web site or a pdf.

markdown and restructuredText are input files, not the end goal.