Great initiative, but beware relying on automatically generated documentation. Keep units documented in the code, and have your higher-level docs handwritten an

Great initiative, but beware relying on automatically generated documentation. Keep units documented in the code, and have your higher-level docs handwritten and hand-structured elsewhere, is the policy I’ve arrived at lately. (It doesn’t make sense to spend resources on having units documented separately from code, because you don’t need such docs unless you’re working with code. Loads of auto-generated docs also gives a false impression of your project being properly documented, which it isn’t unless you also have higher-level hand-written documentation somewhere. Similarly, it doesn’t make sense to keep high-level architecture docs in docstrings, as it’s not tied to specific modules, and you normally need it when you’re thinking big picture as opposed to working with specific code units.) Overall, kudos—good documentation is important. If you’re concerned about writing good documentation, I recommend reading these series by Jacob Kaplan-Moss (of Django core development team): https://jacobian.org/writing/great-documentation/ https://jacobian.org/writing/great-documentation/