I think pandoc can be great for cases when you need to build output documentation in many formats.
But for a lightweight Python project that needs only Markdown and manual pages it might be not the best. This is the reason pandoc-bin package exists saving over 750MB of dependencies.
Natural choices for Python projects are usually docutils and Sphinx. IIRC docutils are ReST-only, so sources have to be ReST instead of Markdown, which is the default for Sphinx as well. I touched it long time ago, but it seems Sphinx supports Markdown source via MyST-Parser.
Alternatively, which is what I'd go with, there's scdoc by Drew DeVault. It's a tiny binary that converts almost-Markdown (which is rendered excellently by GitHub UI) to manual pages and does it well. It's used by sway, Bemenu and I see more and more projects adapting it regardless of what language they're written in, but it's very popular among minimalist and suckless projects in C.
That will help keep project's documentation up-to-date and easy to update without unnecessary frameworks to do that efficiently.
Thoughts?
I think pandoc can be great for cases when you need to build output documentation in many formats.
But for a lightweight Python project that needs only Markdown and manual pages it might be not the best. This is the reason pandoc-bin package exists saving over 750MB of dependencies.
Natural choices for Python projects are usually docutils and Sphinx. IIRC docutils are ReST-only, so sources have to be ReST instead of Markdown, which is the default for Sphinx as well. I touched it long time ago, but it seems Sphinx supports Markdown source via MyST-Parser.
Alternatively, which is what I'd go with, there's scdoc by Drew DeVault. It's a tiny binary that converts almost-Markdown (which is rendered excellently by GitHub UI) to manual pages and does it well. It's used by sway, Bemenu and I see more and more projects adapting it regardless of what language they're written in, but it's very popular among minimalist and suckless projects in C.
That will help keep project's documentation up-to-date and easy to update without unnecessary frameworks to do that efficiently.
Thoughts?