Thoughts on documentation?

[audreyfeldroy]

I'm at PyBeachLA right now about to run sprints, and I think I can get some sprinters here involved. Docs are usually a good starting point for people who aren't ready to jump into code yet.

I'm thinking a docs/ folder with Markdown files, connected via webhook to ReadTheDocs.org?

Or do you have other suggestions/ideas?

[andreagrandi]

Markdown is fine! I've no direct experience in auto generating the docs and pushing to ReadTheDocs but I imagine it's possible through some API integration.

If you are also interested in API docs, FastAPI auto generates it.

p.s: PyBeachLA sounds cool! Let me check how to make you admin of this project. I trust you if you need to add other people to the project.

[audreyfeldroy]

Sounds good, I'll work on getting this started before the sprinters arrive.

[audreyfeldroy]

It got really hectic and I got pulled away from the laptop...will get back to it on my own when I have a chance, unless someone else gets to it first.

FastAPI auto-generated docs sound awesome!

[fundor333]

Suggestion: 2 documentation.

One with the explanation about what it is and how to use -> Handwritten One with the api about how the single endpoint work -> Autogen

In this way you have a HOW TO USE it or a generic explanation about this project and HOW THIS SINGLE ENDPOINT WORK that explain the single point and it's all time describing the code without human help

[fundor333]

In this way we can use the handwritten docs as a path. If you have a beacon or a path is easer to develop code and a easy to use endpoint

[andreagrandi]

Yes, we can have both. The auto generated one will need some "help" from our side (we need to add some documentation and docstrings to the methods) but it's self maintaining. The other one will be the one we host in the static pages of the project. I think we can use mkdocs and generate something like FastAPI one https://fastapi.tiangolo.com