🔒 Need help with documenting my project: md or rst?

[fickle robin]

Hi, I wanted to develop documentation for my python project. I'm thinking in terms of the following pages:

1. How-to guides
2. App architecture
3. Contribution guidelines
4. In-depth per package, module and function documentation, possibly autogenerated from the doc strings in the code.

I'm at a crossroads at what to do? I have the following options:

1. Create md files for all the above topics manually and link them through README.md. This is perfect for GitHub as it renders markdown natively. However, I might have to copy paste the doc strings manually.
2. Generate rst documentation only. Use sphinx to generate the HTML and use readthedocs to host it. In the readme, just put extremely basic info and the link to the readthedocs.

What do you suggest? What are the big projects using these days?

[pallid fiber]

@fickle robin

Python help channel opened

Remember to:

• Ask your Python question, not if you can ask or if there's an expert who can help.
• Show a code sample as text (rather than a screenshot) and the error message, if you've got one.
• Explain what you expect to happen and what actually happens.

:warning: Do not pip install anything that isn't related to your question, especially if asked to over DMs.

Closes after a period of inactivity, or when you send !close.

[drifting compass]

Most Python projects use Sphinx for generating their docs and then you host that on readthedocs or some other service. Do note that Sphinx is indeed capable of using Markdown files, but using RST is also fine.

[fickle robin]

Hi @drifting compass, thank you for the prompt response. My natural inclination is with markdown, so I would love to use that! I'll check out the link that you shared! Have you tried it personally? What was your experience like?

[drifting compass]

I haven't used it that much as I tend to just use rst with Sphinx.

[fickle robin]

Aah, okay! Do you have any source that's relevant to the state of sphinx in 2024? I searched around a lot, but there are a lot of old guides that point out to using sphinx-apidoc, though it's not mentioned in the latest documentation. I just want a solution, where I give it the location of my code files (packages) and it would extract the doc strings from them and be done with it 😁

[drifting compass]

The Sphinx docs have a Quickstart which seems to cover the basics pretty well. If you want to upload to ReadTheDocs, they also have an import guide.

[gritty sigil]

Sphinx is a good option, yes.
Another would be MkDocs and writing in markdown.
For instance, docs for FastAPI are written using Material for MkDocs theme:
https://squidfunk.github.io/mkdocs-material/

[fickle robin]

Hi @gritty sigil, I checked out MkDocs, it looks promising. If it works then the documentation can work on both GitHub as well as on a custom site!

[pallid fiber]

Python help channel closed

This help channel has been closed and it's no longer possible to send messages here. If your question wasn't answered, feel free to create a new post in #1035199133436354600. To maximize your chances of getting a response, check out this guide on asking good questions.