Open brunolnetto opened 9 months ago
Hi @brunolnetto thanks for the comments, and I'm always happy to have help on documentation.
You'll see I've offloaded most of the documentation to this folder where I tend to keep it much more up-to-date than the readme's. https://github.com/whythawk/full-stack-fastapi-postgresql/tree/master/docs
The "source of truth" will always be these docs first, with me frequently forgetting the generated readme's (front- and backends).
At some stage, when I have time, I'll be upgrading to Pydantic 2.0, and then the documentation may need to change again (not too sure what the implications are to the stack). Plus, I'm also considering whether I should integrate i18n directly through the stack. I'm busy with a project that requires static and dynamic i18n, and the complexity is sufficient to think it may be useful to others to have a base project with that demonstrated.
Anyway, safe to say that the stack documentation could do with a review from someone else with a better eye to what less experienced FastAPI developers may need.
Thanks ...
Among ideas, there is cartographic map or summary of the solution. For example, cite which libraries were used for:
For each of topics above, cite what was placed where. It will give the future developer YOUR glimpse of how the libraries work together and what you thought while developing the project.
Also, a refactor stage is welcome based on reading of old README.md files on root and {{cookiecutter.project_slug}}
. After it, I recommend to erase the old ones. This anew structure will require the above summary, or some reading order to guide the reader.
Update:
I made as requested on docs/development-quide.md
for development. The configuration setup requires some meta categories:
Since my own ignorance, I am unaware of some above. I came up to some suggestions, if you may implement them:
totp
is missing on documentation; smtp
;main: domain_main, traefik_constraint_tag staging: domain_staging, traefik_constraint_tag_staging
pgadmin
related information make me able to perform database privilege modifications, right?docker_image
-related configurations seems too much customization IMHO;I have never used docker_swarm
, neo4j
, traefik
, flower
, sentry
. Which means, I will need either your help or further reading.
Thanks for your work, again!
Hey @brunolnetto sorry, haven't forgotten, just been a bit overwhelmed on a project. Will get to this during December.
Sure, take your time. The current doc state is ok. IMH, an empathetic documentation however allows any seniority level to use your boilerplate.
First of all, congratulations 🥳 ! This is by far the best repository I have seen in a long time. I really expected to have something similar while developing my first FastAPI boilerplate.
My suggestion may sound somewhat junior-level, please, do not judge me. BUT I like to have changes and actions STRICTLY CLEAR, which your documentation succeeds, in a verbose mode, which maybe well for someone with more experience. Do not take me wrong, but this repository would benefit from collapsable components to summarize the documentation, like I helped with here, particularly this page. Also, explicit citations on where to perform customization, like the cookiecutter.json, pointers of what to read and why for the very beginning is very appreciated (these instructions appears on advanced mathematics textbooks).
I can suggest my own changes as a pull request if you like, but I need your thumbs up first.
Take a look at my fork repo:
Anyhow, once more CONGRATULATIONS AND THANKS FOR THIS REPOSITORY! 🥳