Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Thoughts on documentation? #3

Open
audreyfeldroy opened this issue Feb 29, 2020 · 6 comments
Open

Thoughts on documentation? #3

audreyfeldroy opened this issue Feb 29, 2020 · 6 comments
Labels
question Further information is requested

Comments

@audreyfeldroy
Copy link
Collaborator

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?

@audreyfeldroy audreyfeldroy added the question Further information is requested label Feb 29, 2020
@andreagrandi
Copy link
Owner

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
Copy link
Collaborator Author

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

@audreyfeldroy
Copy link
Collaborator Author

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
Copy link
Collaborator

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
Copy link
Collaborator

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
Copy link
Owner

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
question Further information is requested
Projects
None yet
Development

No branches or pull requests

3 participants