Question

I would like to write a documentation for one of my Django based project. I found that Django people uses reStructureText and Sphinx for this purpose. I have following queries.

• How do I get started with writing documentations using reStructureText and Sphinx?
• What best practices should I follow so that documentation remain well-organized, versioned easy to understand and easy to manage?

Answer 1

Documentation of sphinx is here: https://www.sphinx-doc.org

• You start by running sphinx-quickstart.
• "Well organized" is really your own matter. This depends on your taste and your project.
• "Easy to manage": include doctests in your code documentation and autodoc in you sphinx setup. This way you can always see if your documentation matches your code when you run your testsuit. (But only use doctest for testing your docs, to test your code, you should have separate unit tests, otherwise the documentation will be unusable…)
• As for "easy to understand", this is really up to you.