search

andreagrandi / covid-api

COVID19 Api based on Johns Hopkins CSSE data
MIT License
60 stars 17 forks source link

Thoughts on documentation? #3

Open audreyfeldroy opened 4 years ago

audreyfeldroy commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

audreyfeldroy commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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