dokterbob
commented
1 year ago @ayushin Nice to meet you!
These docs are in fact fully generated based on the actual code. As much as I'm with you on using something like pydoc for extracting class and method-specific documentation, I do consider it essential to have a small level of overview in the documentation, in addition to docstrings.
Specifically, for outsiders coming in (e.g. potential contributors, new team members), having a single point of access to get started with a project without having to read all the code and then tying it together saves a lot of time, motivates people and, last but not least, offloads leads/maintainers. It's effectively a FAQ to be more DRY and focused on moving projects forward if your usual questions are already answered and do not require asking team members the same question.
Especially outside users or contributors will be put off by this and simply not use an app which is not forthcoming in terms of documentation.
As it stands, I do think the README (largely based on the pre-existing structure, e.g. sections consisting solely of '...') is arguably a bit too verbose. Perhaps a short overview in the README for outsiders to judge whether this is the project for them and how to give it a minimal test-run, together with a link to ReadTheDocs is a good practice. The RTD could go into the how's and why's of architectural decisions and could include auto-generated class and method-level documentation.
Unpretentious README-basics.
Just me trying to understand this project, it's dependencies and role within/relationship to DjangoFlow.
Unapologetically generated, arguably better than '...' as reported in #24.
I've currently added disclaimers:
Happy to remove them, e.g. when project owner/maintainer judges instructions to be correct.