Merge pull request #478 from zapta/develop

Minor doc and test coverage tweaks.

DEVELOPER.md → DEVELOPERS.md

@@ -1,6 +1,6 @@
-# Apio Developers Hints
+# Apio Developers Information
 
-This file is not intended for APIO users.
+This file is intended for APIO developers.
 
 ## Pre commit tests
 Before submitting a new commit, make sure to run successfuly the following command
@@ -10,6 +10,39 @@ in the root directory of the repository.:
 make check
 ```
 
+For complete tests with several python versions run the command below. 
+
+```shell
+make check_all
+```
+
+For quick tests that that don't load lengthy packagtes from the internet
+run the command below. It will skip all the tests that require internet 
+connection.
+
+```shell
+make test
+```
+
+For running the linters only, run
+
+```shell
+make lint
+```
+
+## Test coverage
+
+When running any of the commands below, a test coverage is generated in the
+``htmlcov``, to view it open ``htmlcov/index.html`` it with a browser. The ``htmldev`` directory is not checked in the apio repository.
+
+```
+make test          // Partial coverage by offline tests
+make check         // Full coverage
+make check_all     // Full coverage by the last python env run.
+```
+
+
+
 ## Running an individual APIO test
 
 Run from the repo root. Replace with the path to the desire test. Running ``pytest`` alone runs all the tests.
@@ -31,7 +64,7 @@ python apio_run.py build --project_dir ~/projects/fpga/repo/hdl
 ## Running apio in the Visual Studio Code debugger.
 
 The ``apio`` repository contains at its root the file ``.vscode/launch.json`` with debug
-target for most of the ``apio`` commands. Make sure to open the roo folder of the repository for VSC to recognize the targets file. To select the debug target, click on the debug icon on the left sidebar and this will display above a pull down menu with the available debug target and a start icon.
+target for most of the ``apio`` commands. Make sure to open the root folder of the repository for VSC to recognize the targets file. To select the debug target, click on the debug icon on the left sidebar and this will display above a pull down menu with the available debug target and a start icon.
 
 [NOTE] This method doesn't not work for debugging the SConstruct scripts since they are run as subprocesses of the apio process. For debugging SConstruct scripts see the next section.
 

tox.ini

@@ -1,6 +1,14 @@
 # Automated testing.
 # https://tox.wiki/en/latest/config.html
 
+# NOTE: Since we don't use clean and --cov-append, the tests coverage is from the 
+# last python env that is run. Shouldn't be a problem though since we expect similar
+# coverage from all python env (we don't branch much on python version).
+
+# NOTE: The coverage report doesn't include the files in the scons/ directory
+# which are run in a subprocess. This includes python files such as
+# scons_util.py and the SConstruct files.
+
 # Useful commands
 # 
 # Run everything:
@@ -73,7 +81,7 @@ deps =
     pytest-cov==5.0.0
 
 commands = 
-    python -m pytest --cov-report html --cov apio test {posargs}
+    python -m pytest --cov --cov-report=html apio test {posargs}
 
 
 # ----------------------------------------------------