Python-guidelines.md

@@ -23,6 +23,42 @@ Tools to use to automatically test style and/or fix it.
 - [flake8-docstring](https://pypi.org/project/flake8-docstrings/):
   follows PEP257.
 
+Documentation
+"""""""""""""
+
+Tools:
+
+- [reStrucuturedText](https://www.https://docutils.sourceforge.io/rst.html)
+- [Sphinx](https://www.sphinx-doc.org/): makes it easy to create intelligent
+  and beautiful documentation.
+
+Testing
+"""""""
+
+- [pytests](https://pytest.org): makes it easy to write small tests.
+- [tox](https://tox.readthedocs.io/): virtualenv-based automation of test
+  activities.
+- [coverage](https://coverage.readthedocs.io/): a tool for measuring code
+  coverage of Python programs.
+
+Packaging
+"""""""""
+
+In general, develop with last versions of the dependencies.
+When packaging, ensure your application works with older stable dependencies.
+
+- [setuptools](https://setuptools.readthedocs.io/en/latest/setuptools.html)
+- [distributing packages](https://packaging.python.org/guides/distributing-packages-using-setuptools/)
+
+Why to use `setuptools` instead of `requirements.txt`:
+
+- install your own package, not only the dependencies
+- don't depend on specific "snapshot" versions
+- facilitates the creation of system packages
+
+See also: [install requires vs requirements](https://packaging.python.org/discussions/install-requires-vs-requirements/),
+[setup vs requirements](https://caremad.io/posts/2013/07/setup-vs-requirement/)
+
 Other conventions and tools
 ---------------------------
 
@@ -40,4 +76,8 @@ https://realpython.com/python-code-quality/
 https://firefox-source-docs.mozilla.org/code-quality/index.html
 
 
-Other tools: https://realpython.com/python-code-quality/
\ No newline at end of file
+Human language:
+
+- [codespell](https://github.com/codespell-project/codespell/): Fix common
+  misspellings in text files. It’s designed primarily for checking misspelled
+  words in source code, but it can be used with other files as well.