Setting up python development tools
Github setup
We use Github to store our code. To make it easier to push changes from the Pi to Github, on the Github account, in "Settings > SSH and GPG keys", add the Pi's public key.
Create a repo on Github. On the repo's homepage, find the green button named "Code", and copy the contents of SSH into the clip board.
Open a terminal on the Pi, go to a desired location, and issue git clone contents_in_clipboard
. If git
has not been installed on, do sudo apt-get install git
first.
Creating a virtualenv venv
Our version of Raspberry Pi OS comes with python 3.9.2
, which is sufficient for our purpose. However, it is good practice to use a local environment for each project, so that different projects do not clash with one another.
Go the to project's folder. The following creates a new environment in a local folder named venv
.
python -m venv --copies --clear ./venv
We will put our code in a directory name src
in the repo. To make the python
interpreter know about this, open ./venv/bin/activate
, and add the following to the end
export PYTHONPATH=path_to_src_folder
To activate the environment, use
source ./venv/bin/activate
The name venv
should appear in the command prompt, indicating that the environment has been activate. New packages can now be installed using pip
.
Use deactivate
to exit the environment.
We do not want git to keep track of the files in .venv
. To this end, at the top level of the project's folder, create a new file named .gitignore
and add .venv/
in it.
VS Code setup
We will primarily be doing remote development using VS Code. Use the Remote Explorer to open the folder created in the previous step by git clone
. This folder will appear in the Remote Explorer, so that we can simply click on it to open.
Click on the Extensions icon and install the Python extension pack in VS Code. The Black Formatter extension could also be installed to help automatical code formatting. Then open the Command Palette, type Python: Select Interpreter
> "+ Enter interpreter path...". In the window, find the folder that contains the venv
folder, and within it, locate bin/python
.
Readthedocs setup
We would like to use Markdown to document our progress. Readthedocs (https://readthedocs.org/) provides free hosting services. Their website provides a fairly detailed description about how to link a Github account with a Readthedocs account, how to import data from Github, and how to enable writing documentation using Markdown with mkdocs
. In what follows, we outline the main steps and describe things that have tripped us up.
-
It is quite useful to be able to write, build and view documentations locally. To this end, go to the project's folder, and activate the
venv
using the steps described above. Issuepip install mkdocs
to add the tool into thevenv
. Then while at the top level of the project's folder, usemkdocs new .
to create a Markdown documentation set-up. This will add a folderdocs
andmkdocs.yml
to the project. Indocs
, we will findindex.md
. This is the total level entry point for our documentation. -
Once we have written some documentation, we can use
mkdocs serve
. This will compile the Markdown code and open a web browser, so that we can see the results. -
Go to
https://readthedocs.org/
and follow the tutorial on setting up an account and importing projects from Github. On "Project Details" page, check "Edit advanced project options" before clicking on "Next". On the next page, change "Documentation type" to "Mkdocs". -
After the project has been imported, click on the "Admin" button. The go to "Adavanced settings", and check "Build pull requests for this project".
With these set-ups, everytime we push changes from the Pi to Github, the changes will also trickle down to Readthedocs, and trigger a new build of the documentation.
It is a good idea to pin some of the key libraries mkdocs
uses (including itself); this reduces the risk of compatibility problems caused by library upgrades. See .readthedocs.yaml
and docs/requirements.txt
in the Github repo.
Note: If you want to see the updated documentation build, click on the large green View Docs button on the project's homepage on Readthedocs. However, make sure you refresh your web browser. Otherwise the browser would probably just load what it has put into the cache, instead of the up-to-date build. We spent a long time trying to figure why a successful Readthedocs build did not result in the website being updated, only to find out that, by merely copying and pasting the web link into the browser, we had been just looking at the browser's cached version.