Merge pull request #40 from SciKit-Surgery/39-final-release-1.0.0

39 - final release 1.0.0

README.rst

@@ -28,8 +28,8 @@ SciKit-Surgery Tutorial on Software Development for Clinical Translation
    :target: https://twitter.com/scikit_surgery?ref_src=twsrc%5Etfw
    :alt: Follow scikit_surgery on twitter
 
-Author(s): Stephen Thompson
-Contributor(s): Miguel Xochicale, Thomas Dowrick and Matt Clarkson
+Author(s): Miguel Xochicale and Stephen Thompson
+Contributor(s): Sujon Hakim, Mian Asbat Ahmad, Thomas Dowrick and Matt Clarkson
 
 This is the SciKit-Surgery Tutorial on Software Development for Clinical Translation. It is targeted at researchers working in medical imaging and computer aided interventions, who want to maximise the impact of their work by publishing robust and reusable code.
 The tutorial will guide the user through using the SciKit-Surgery Python template to create a well written and reusable algorithm library. 

doc/00_Introduction.rst

@@ -15,15 +15,12 @@ to write and publish robust, documented and tested implementations of their
 algorithms. The skills learnt will help the user disseminate their research and
 translate their research to clinical applications. 
 
-After completing the tutorial the user will have;
-
-- Used the SciKit-Surgery Python Template to create, test, and publish an implementation of a simple 
-  image processing algorithm.
-
 After the completing the tutorial the user should be able to;
 
-- Use gitlab to create and manage a software repository.
-- Use tox and gitlab to test the software and create continuous integration tests.
+- Use the SciKit-Surgery Python Template to create, test, and publish an implementation of a simple
+  image processing algorithm.
+- Use GitHub to create and manage a software repository.
+- Use tox and GitHub to test the software and create continuous integration tests.
 - Create documentation for the software using docstrings and sphinx.
 - Publish the documentation to readthedocs
 - Publish the software to PyPi.

doc/01_Starting_Out.rst

@@ -6,88 +6,53 @@
 Getting Started
 ===============================================
 
-Packages and other requirements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-scikit-surgery-sphere-fitting require pandoc: universal document converter `pandoc_installation`_.
-
-Virtual environments
-~~~~~~~~~~~~~~~~~~~~
+Packages, other requirements, and 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 use the following yml file with all dependencies.
 ::
 
-   ## Create scikit-surgeryTUTORIAL02VE.yml in your favorite location with the following content:
-   ##
-   ##  scikit-surgeryTUTORIAL02VE.yml
-   ##
-   ## 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 --file *VE.yml --prune
-   ## ACTIVATE CONDA ENV: conda activate *VE
-   ## REMOVE CONDA ENV: conda remove -n *VE --all
-
-   name: scikit-surgeryTUTORIAL02VE
-   channels:
-     - conda-forge
-   dependencies:
-     - python=3.8
-     - pip>=23.0.1
-     - pip:
-        ##############################################
-        ## requirements.txt
-        - cookiecutter
-        - numpy
-        - vtk>=9.2.5
-        - scikit-surgeryvtk==2.0rc0
-        - scikit-surgeryimage>=0.10.1
-        - scikit-surgerycore>=0.6.10
-        ###############################################
-        ## requirements-dev.txt
-        ##############################################
-        - scipy
-        - tox
-        - pytest
-        - pylint
-        - sphinx
-        - sphinx_rtd_theme
+   conda update -n base -c defaults conda
+   conda create -n sst02VE python=3.8 pip -c conda-forge
+   conda activate sst02VE
+   pip install -r requirements.txt
+   pip install -r requirements-dev.txt
 
 Creating PythonTemplate
 ~~~~~~~~~~~~~~~~~~~~~~~
-Step 1: Create a local directory to host your project.
+Step 1: Launch your conda environment
+::
+
+  conda activate sst02VE
+
+Step 2: Create a local directory to host your project.
 
-Step 2: The SciKit-Surgery Python Templates uses `cookiecutter`_ to generate a project from a
+Step 3: The SciKit-Surgery Python Templates uses `cookiecutter`_ to generate a project from a
 templates. Start by checking you have cookiecutter installed. Otherwise activate your virtual environment.
 ::
 
   pip install cookiecutter
 
-Step 3: Use the Python Template to create your new project.
+Step 4: Use the Python Template to create your new project.
 This tutorial uses a `sphere fitting algorithm`_ as an example case, as it 
 strikes a nice balance between simplicity and usefulness. Fitting models to data
 is a key part of medical image computing, so hopefully the user can see how their own 
 algorithms could be inserted into the software template.
 ::
 
-  conda activate scikit-surgeryTUTORIAL02VE
   cookiecutter https://github.com/SciKit-Surgery/PythonTemplate.git
 
 If that doesn't work try,
 ::
 
   python -m  cookiecutter https://github.com/SciKit-Surgery/PythonTemplate.git 
 
-Follow the prompts, we should call our project something descriptive, so if you're doing sphere fitting:
+Step 5: Follow the prompts, we should call our project something descriptive, so if you're doing sphere fitting:
 ::
 
   project_name [My New Project]: scikit-surgery-sphere-fitting
   project_slug [scikit-surgery-sphere-fitting]: sksurgeryspherefitting
-  project_description [scikit-surgery-sphere-fitting is a Python package]:
-                                  scikit-surgery-sphere-fitting implements
-                                  a least squares sphere fitting algorithm,
-                                  to read a vtk poly data file, a config file,
-                                  and outputs the fitted sphere.
+  project_description [scikit-surgery-sphere-fitting is a Python package]: scikit-surgery-sphere-fitting implements a least squares sphere fitting algorithm, to read a vtk poly data file, a config file, and outputs the fitted sphere.
   pkg_name [sksurgeryspherefitting]:
   Select repository_server:
   1 - https://github.com
@@ -112,6 +77,17 @@ Follow the prompts, we should call our project something descriptive, so if you'
   Choose from 1, 2, 3 [1]: 1
   copyright_holder [University College London]:
 
+Create a new GitHub repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You might need to create your Secure Shell Protocol (SSH) keys `here`_.
+User also needs to `Adds a new SSH key to GitHub account`_.
+Then, create a new project on GitHub (or GitLab, WeissLab or your preferred git host), making sure the URL matches
+what you set in step 3 (e.g., `project_url [https://github.com/mxochicale/sksurgeryspherefitting]`.
+
+.. image:: new_project_github.png
+   :height: 400px
+   :alt: Create new project on GitHub
+   :align: center
 
 Initialise git repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -120,22 +96,16 @@ Enter the source directory and initialise git repository.
 
   cd sksurgeryspherefitting/
   git init
+  git branch -m main
   git add .
   git commit -m "Initial commit of my sphere fitter"
 
-Create a new project on GitHub (or GitLab, WeissLab or your preferred git host), making sure the URL matches
-what you set in step 3 (e.g., `project_url [https://github.com/mxochicale/sksurgeryspherefitting]`.
-
-.. image:: new_project_github.png
-   :height: 400px
-   :alt: Create new project on weisslab
-   :align: center
 
 Add the remote to git and push your first commit
 ::
 
-   git remote add origin https://github.com/mxochicale/sksurgeryspherefitting.git
-   git push origin master
+   git remote add origin git@github.com:mxochicale/sksurgeryspherefitting.git
+   git push origin main
 
 Visit the web interface to GitHub (or your preferred git host) and checkout out your first commit
 
@@ -148,8 +118,8 @@ You may notice that it says that your commit failed.
 This refers to the continuous integration test having failed, not that your project was lost.
 By the end this tutorial you will have a green tick where now there is a red cross, for know though, don't worry.
 
-
 .. _`cookiecutter`: https://cookiecutter.readthedocs.io/en/latest/
 .. _`sphere fitting algorithm`: https://scikit-surgery-sphere-fitting.readthedocs.io/en/latest/
-.. _`pandoc_installation` : https://pandoc.org/installing.html
 .. _`conda_installation` : https://conda.io/projects/conda/en/latest/user-guide/install/index.html
+.. _`here` : https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
+.. _`Adds a new SSH key to GitHub account`: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent

doc/03_Git.rst

@@ -6,7 +6,7 @@
 Getting Started with git
 ===============================================
 
-WEISSLab uses `git`_ to control and maintain the source code versioning of
+GitHub uses `git`_ to control and maintain the source code versioning of
 projects made using the Python Template. This tutorial is no 
 substitute for a good understanding of version control in general and 
 `git`_ in particular. We will cover just enough git commands here to get you 

doc/05_StartCoding.rst

@@ -25,11 +25,12 @@ The SciKit-Surgery Python template has already populated this with a couple of e
 These are nice examples, but a bit too simple for our tutorial. So lets delete them and create our own file, 
 sphere_fitting.py. I chose sphere fitting as it was useful for me at the time, feel free to insert your own 
 algorithm at this point.
-The following code uses vim to edit the files, you can use whatever editor you like.
+The following code uses vim to edit the files. See `vim`_ for some basic commands.
+You can use whatever editor you like.
 ::
 
    rm addition.py multiplication.py
-   vi sphere_fitting.py
+   vim sphere_fitting.py
 
 
 Copy and paste the following into your editor.
@@ -99,10 +100,11 @@ That's it, you've written a sphere fitting algorithm using the Python template.
    git push origin 1-testing-tox-lint-pep8
 
 Make sure you include a short message (50 chars or less), including the hashtag #1, (#<IssueID>).
-Hence WEISSlab can link the change to the issue you created earlier.
+Hence GitHub can link the change to the issue you created earlier.
 
 Now anyone with access to your git repository can download and use your algorithm. However they're a lot more 
 likely to do that if they can see that your algorithm does what it's supposed to do. This is where the Python
 template starts being really helpful. 
 
 .. _`See page 44 of this`: https://magazines-static.raspberrypi.org/issues/full_pdfs/000/000/030/original/HelloWorld07.pdf#page=44
+.. _`vim`: https://linuxhandbook.com/basic-vim-commands/

doc/06.1_Linting.rst

@@ -11,7 +11,9 @@ tidily written? However, the aim of the SciKit-Surgery Python template is to hel
 you, but will be downloaded by others, modified and spread about. That's a lot more likely to happen if your code
 can be easily understood by others, and that's what lint helps you do. 
 
-If we scroll back up through the test output we'll start finding some linting errors. Depending on 
+Step 1. Identifying linting errors
+
+If we scroll back up through the test output in your terminal, we'll start finding some linting errors. Depending on
 how well you've cut and pasted you may have other errors, but let's look at the first one I get, which
 looks like this;
 ::
@@ -21,7 +23,10 @@ looks like this;
    sksurgeryspherefitting/ui/sksurgeryspherefitting_command_line.py:14:0: C0301: Line too long (81/80) (line-too-long)
 
 It's telling us that one of the lines is too long in a file in the ui directory. We haven't started on the user 
-interface yet, and the file in question was auto generated by the Python Template. 
+interface yet, and the file in question was auto generated by the Python Template.
+
+Step 2. Editing pylintrc to ignore errors
+
 Let's just tell pylint to ignore the ui directory for the moment. 
 Edit the file pylintrc, which is in the tests directory. Near the top of the file is an entry called 
 ignore, add "ui" to the list of things to ignore;
@@ -31,7 +36,9 @@ ignore, add "ui" to the list of things to ignore;
    # paths.
    ignore=CVS, ui
 
-Now try running tox again (e.g, `tox -r`). If you've cut and pasted the code from earlier, you should get
+Step 3. Running tox again and fixing other errors
+
+Now try running tox again (e.g, `tox -r`). If you've cut and pasted the code from earlier, you should then get
 one linting error;
 ::
 
@@ -49,43 +56,55 @@ one linting error;
 
 
 As you can see, those are minor error that effects readability but you can edit sphere_fitting.py and test_sksurgeryspherefitting.py
-to fix it and rerun tox.
+to fix it and rerun tox (e.g,`tox -r`). If not, read the output and fix any remaining errors.
+
+Step 4. Reformatting code with Pycharm or Visual Code Studio
+
 Pycharm has a `Reformat Code`_ option that can help to fix such readability issues.
-You should now get:
+Similarly, you can do it with `Formatting code in Visual Studio`_.
+
+Step 5. Committing, pushing changes and checking remote linting
+
+Once you have all tests passing, you should now get:
 ::
 
    ______________________________________________________ summary ______________________________________________________
    py36: commands succeeded
    lint: commands succeeded
    congratulations :)
 
-If not, read the output and fix any remaining errors. Once you have all tests passing, commit your changes and push to origin;
+Commit your changes and push to origin;
 ::
 
    git add tests/test_sksurgeryspherefitting.py
    git add setup.py requirements.txt sksurgeryspherefitting/algorithms/sphere_fitting.py tests/pylintrc tests/test_sksurgeryspherefitting.py
    git commit -m "implemented unit test and fixed style errors (#1)"
    git push origin 1-testing-tox-lint-pep8
 
-If you wait a few minutes and visit GitHub, you should be able to see your library commit passing
-with a nice green tick. Congratulations, you have mastered testing and continuous integration testing. 
+If you wait a few minutes and visit GitHub project, you should be able to see your library commit passing
+with a nice green tick in the `action` menu.
+
+Congratulations, you have mastered testing and continuous integration testing.
 
 .. image:: passing_github.png
    :height: 400px
    :alt: Your commit passing on GitHub
    :align: center
 
-Your code is working now. So lets draw a line under it. Use git to merge your branch back to master, 
+Step 6. Merging branch and closing issue
+
+Your code is working now. So lets draw a line under it. Use git to merge your branch back to main,
 and push it to the origin. Then close the issue on GitHub.
 ::
 
-   git checkout master
+   git checkout main
    git merge --no-ff 1-testing-tox-lint-pep8
-   git push origin master
+   git push origin main
    git branch --delete 1-testing-tox-lint-pep8
 
 Go to the GitHub website, and close issue 1.
 
 .. _`PEP 8`: https://www.python.org/dev/peps/pep-0008/
 .. _`pylint`: https://www.pylint.org/
 .. _`Reformat Code`: https://www.jetbrains.com/help/pycharm/reformat-and-rearrange-code.html
+.. _`Formatting code in Visual Studio`: https://code.visualstudio.com/docs/python/editing#_formatting

doc/06_Testing.rst

@@ -50,7 +50,7 @@ go into the test directory,
 And edit the test file 
 ::
 
-   vi test_sksurgeryspherefitting.py
+   vim test_sksurgeryspherefitting.py
 
 The first line imports from the user interface (ui). We'll cover this later in the tutorial, for now let's 
 comment it out 
@@ -166,5 +166,11 @@ now try running tox again, you should see a bunch of output ending something lik
 
 Which tells us that the functional unit tests worked, but that "lint" failed. 
 
+One alternative way to also linting and unit testing your individual files is using:
+::
+
+    pylint --rcfile=tests/pylintrc $LIB_PATH/python_file.py
+    pytest -v -s test/test_name.py
+
 .. _`PEP 8`: https://www.python.org/dev/peps/pep-0008/