Merge branch '55-linting'

README.rst

@@ -50,68 +50,61 @@ Features
 
 .. features-end
 
-Developing
-----------
-
-Virtual environments
-^^^^^^^
-Virtualenv, venv, conda or pyenv can be used to create virtual environments to manage python packages.
-You can use conda env by installing conda for your OS (`conda_installation`_) and the following yml file for its dependencies.
-::
-    ## Some useful commands to manage your conda env:
-    ## LIST CONDA ENVS: conda list -n *VE # show list of installed packages
-    ## UPDATE CONDA: conda update -n base -c defaults conda
-    ## INSTALL CONDA EV: conda env create -f *VE.yml
-    ## UPDATE CONDA ENV: conda env update -f *VE.yml --prune
-    ## ACTIVATE CONDA ENV: conda activate *VE
-    ## REMOVE CONDA ENV: conda remove -n *VE --all
-
-    name: scikit-surgerycalibrationVE
-    channels:
-      - defaults
-      - conda-forge
-      - anaconda
-    dependencies:
-      - python=3.7
-      - pip>=22.2.2
-      - pip:
-         - scikit-surgerycore
-         - scikit-surgeryimage>=0.10.1
-         - opencv-contrib-python-headless<4.6
-         - tox>=3.26.0
-         - pytest>=7.2.0
-         - pylint>=2.15.9
-         - jupyter
-         - numpy>=1.21.6
-         - scipy>=1.7.3
-         - matplotlib
 
 Cloning
-^^^^^^^
+-------
+
 You can clone the repository using the following command:
 ::
 
     git clone https://github.com/SciKit-Surgery/scikit-surgerycalibration
     git clone git@github.com:SciKit-Surgery/scikit-surgerycalibration.git # Alternatively, use password-protected SSH key.
 
-Launching virtual env
-^^^^^^^^^^^^^
-Conda virtual environment is used to reproduce same python dependencies
+
+Developing
+----------
+
+We recommend using `anaconda`_ or `miniconda`_ to create a python 3.7 environment,
+then using `tox`_ to install all dependencies inside a dedicated `venv`_. We then use
+github `actions`_ to run a matrix of builds for Windows, Linux and Mac and various python versions.
+
+All library dependencies are specified via ``requirements-dev.txt`` which refers to ``requirements.txt``.
+
+So, assuming either `anaconda`_ or `miniconda`_ is installed, and your current working directory is the root directory of this project:
 ::
+    conda create --name scikit-surgery python=3.7
+    conda activate scikit-surgery
+    pip install tox
+    tox
 
-    conda activate scikit-surgerycalibrationVE
+As the `tox`_ command runs, it will install all dependencies in a sub-directory ``.tox/py37`` (Linux/Mac) or ``.tox\py37`` (Windows).
+`tox`_ will also run pytest and linting for you.
 
+To run commands inside the same environment as `tox`_, you should:
+::
+    source .tox/py37/bin/activate
 
-Running tox
-^^^^^^^^^^^^^
-Tox is used to check package builds, docs, requirements and installs correctly under different environments.
+on Linux/Mac, or if you are Windows user:
 ::
+    .tox\py37\Scripts\activate
 
-    tox
+Then you can run pytest, linting, or directly run python scripts, and
+know that the environment was created correctly by `tox`_.
+
+
+Generating documentation
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The simplest way is again using `tox`_.
+::
+    tox -e docs
+
+then open ``docs/build/html/index.html`` in your browser.
 
 
 Running tests
 ^^^^^^^^^^^^^
+
 Pytest is used for running unit tests:
 ::
 
@@ -129,6 +122,7 @@ This code conforms to the PEP8 standard. Pylint can be used to analyse the code:
 
 Installing
 ----------
+
 You can pip install directly from the repository as follows:
 ::
 
@@ -137,11 +131,14 @@ You can pip install directly from the repository as follows:
 
 
 Contributing
-^^^^^^^^^^^^
+------------
+
 Please see the `contributing guidelines`_.
 
+
 Useful links
-^^^^^^^^^^^^
+------------
+
 * `Source code repository`_
 * `Documentation`_
 
@@ -164,6 +161,11 @@ Supported by `Wellcome`_ and `EPSRC`_.
 .. _`University College London (UCL)`: http://www.ucl.ac.uk/
 .. _`Wellcome`: https://wellcome.ac.uk/
 .. _`EPSRC`: https://www.epsrc.ac.uk/
+.. _`anaconda`: https://www.anaconda.com/
+.. _`miniconda`: https://docs.conda.io/en/latest/miniconda.html
+.. _`tox`: https://tox.wiki/en/latest/
+.. _`venv`: https://docs.python.org/3/library/venv.html
+.. _`actions`: https://github.com/SciKit-Surgery/scikit-surgerycalibration/actions
 .. _`contributing guidelines`: https://github.com/SciKit-Surgery/scikit-surgerycalibration /blob/master/CONTRIBUTING.rst
 .. _`license file`: https://github.com/SciKit-Surgery/scikit-surgerycalibration /blob/master/LICENSE
 .. _`conda_installation` : https://conda.io/projects/conda/en/latest/user-guide/install/index.html

docs/.gitignore

@@ -1,5 +1,4 @@
-/sksurgerycalibration.rst
-/sksurgerycalibration.*.rst
+/sks*.rst
 /modules.rst
 /versioneer.rst
 /build

tox.ini

@@ -25,7 +25,7 @@ commands=pylint --rcfile=tests/pylintrc sksurgerycalibration tests
 
 [testenv:docs]
 basepython=python3.7
-changedir = doc
+changedir = docs
 commands = sphinx-build -M html . build
 
 [testenv:installer]