From 6b7c492efee8e20badee9a9cd82d3e983ef18e7e Mon Sep 17 00:00:00 2001 From: hannah cushman garland Date: Thu, 25 Aug 2022 13:12:12 -0500 Subject: [PATCH] Add Sphinx/autodoc docs, connects #162 (#289) * Add Sphinx/autodoc docs, connects #162 * Add missing contents link * Update Python contents link --- README.md | 2 ++ python/README.md | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 python/README.md diff --git a/README.md b/README.md index aa072fd..01f9246 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,8 @@ _In alphabetical order and including links to external repository-based document - [Interacting with a remote database](postgres/Interacting-with-a-remote-database.md) - [Dumping and restoring a Postgres database](postgres/Dump-and-restore-Postgres.md) - [Dockerizing Postgres](postgres/Dockerizing-Postgres.md) +- [Python](python/) + - [Python project documentation](python/) - [Reproducible data analysis](data-analysis/) - [Scraping](scraping/) - [`lxml` for web scraping](scraping/lxml-for-web-scraping.md) diff --git a/python/README.md b/python/README.md new file mode 100644 index 0000000..c7e9893 --- /dev/null +++ b/python/README.md @@ -0,0 +1,37 @@ +# 🐍 Python + +This directory contains research and best practices related to our favorite programming language, Python. + +### Contents + +- [Python project documentation](#python-project-documentation) + +## Python project documentation + +At DataMade, we believe in [better living through documentation](https://datamade.us/blog/better-living-through-documentation/). For Python projects (libraries and Django projects alike), we recommend writing documentation using [Sphinx](https://www.sphinx-doc.org/en/master/index.html) and [`autodoc`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html), and hosting that documentation on [Read the Docs](https://readthedocs.org/). + +### When to write docs + +Documentation is crucial for software intended to be used by others. That means open-source libraries and projects we plan to hand off to other developers should be documented. + +While docs are discretionary for internal projects, we highly recommend documenting a minimum of system and application dependencies and local development instructions. These are included in [the DataMade README template](https://github.com/datamade/readme-template). + +**If your project calls for docs, don't wait to start writing!** It's much easier to write docs as you implement new features than it is to retroactively document an entire codebase. + +### Sphinx and autodoc + +[Sphinx](https://www.sphinx-doc.org/en/master/index.html) is a Python documentation generator. [Its autodoc extension](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) allows you to interweave prose with docstrings from your code in your final documentation. + +Use [the Sphinx quickstart documentation from ReadTheDocs](https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html) generate the files you'll need to compose your documentation, then add your first draft to `docs/index.rst`. See [the reStructuredText spec](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html) and [autodoc documentation](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html), respectively, for more on correctly formatting your documentation file/s and how to leverage autodoc to include content from your docstrings. + +See the [`census_area.core` module](https://github.com/datamade/census_area/blob/master/census_area/core.py) and [`docs/index.rst`](https://raw.githubusercontent.com/datamade/census_area/master/docs/index.rst) for an example of combined documentation, powered by this stack. + +### Deploying your docs + +To deploy your documentation, you will need to [sign up for Read the Docs using your GitHub account](https://readthedocs.org/accounts/signup/). Then, follow [the instructions for importing documentation to Read the Docs](https://docs.readthedocs.io/en/stable/tutorial/index.html#first-steps) to deploy your docs. + +By default, your docs will be rebuilt on each commit to your default branch (e.g., `master` or `main`). You can customize the default branch on the Read the Docs site by going to `${YOUR_PROJECT}` > Admin > Advanced settings, and selecting the branch you want to autobuild from. + +You can also [configure Read the Docs to build your docs on pull requests](https://docs.readthedocs.io/en/stable/pull-requests.html) so you can preview changes before you deploy them. + +See the [`census_area`](https://github.com/datamade/census_area) and [`dedupe`](https://github.com/dedupeio/dedupe) packages for examples of projects configured to be deployed to Read the Docs.