Merge branch 'skeleton'

Author: gilesknap

.github/workflows/code.yml

@@ -100,11 +100,13 @@ jobs:
       - name: Install with locked dependencies
         if: matrix.lock
         run: |
-          touch requirements.txt requirements_dev.txt
+          echo '# runtime dependencies' > requirements.txt 
+          echo '# developer dependencies' > requirements_dev.txt
+          # above avoids zero length requirements files
           pip install -r requirements.txt -e .
-          pip freeze --exclude-editable > requirements.txt
+          pip freeze --exclude-editable >> requirements.txt
           pip install -r requirements_dev.txt -e .[dev]
-          pip freeze --exclude-editable > requirements_dev.txt
+          pip freeze --exclude-editable >> requirements_dev.txt
 
       - name: Install with latest dependencies
         if: ${{ ! matrix.lock }}

CONTRIBUTING.rst

@@ -30,6 +30,38 @@ Use vscode devcontainer as follows::
     $ tox -p
 
 
+To run locally
+~~~~~~~~~~~~~~
+
+Get the source source code and run the unit tests directly
+on your workstation as follows::
+
+    $ git clone git://github.com/epics-containers/python3-pip-skeleton.git
+    $ cd python3-pip-skeleton
+    $ virtualenv .venv
+    $ source .venv/bin/activate
+    $ pip install -e .[dev]
+    $ tox -p 
+
+In both cases tox -p runs in parallel the following checks:
+
+  - Build Spinx Documentation
+  - run pytest on all tests in ./tests
+  - run mypy linting on all files in ./src ./tests
+  - run pre-commit checks:
+
+    - run flake8 style checks against all source
+    - run black formatting checks against all source
+
+Use vscode devcontainer as follows::
+
+    $ git clone git://github.com/epics-containers/python3-pip-skeleton.git
+    $ vscode python3-pip-skeleton
+    Click on 'Reopen in Container' when prompted
+    In a vscode Terminal:
+    $ tox -p
+
+
 To run locally
 ~~~~~~~~~~~~~~
 
@@ -142,6 +174,14 @@ When this happens:
 
 .. _release: https://github.com/epics-containers/python3-pip-skeleton/releases
 
+
+Checking Dependencies
+---------------------
+
+To see a graph of the python package dependency tree type::
+
+    pipdeptree
+
 Apart from this, ``main`` and ``skeleton`` should always be deployable,
 and are considered the latest release.