Doc improvements

.gitignore

@@ -80,3 +80,4 @@ MANIFEST
 *.exe
 *.out
 *.app
+/.ptp-sync/

doc/README.md

@@ -0,0 +1,63 @@
+# pFIRE documentation
+
+### In code documentation
+This project is mainly writte in C++. In code documentation is generated using 
+Doxygen documentation that can be generated running:
+
+
+```
+# In pFIRE source folder run
+doxygen
+
+```
+
+Doxygen is a tool to generate in code documentatation: [doxygen](https://www.doxygen.nl)
+
+### User and developer documentation
+
+All the remaining documentation is located in the `/doc` subfoldeer and is 
+written using simple text files in Markdown and Restructured text format.
+[Sphinx](https://www.sphinx-doc.org/en/master/) with Readthedocs template are used 
+to generate documentation both in HTML and PDF format.
+
+Documentation here provided is automatically generated and made available at:
+
+Create Python virtual environment and install Sphinx dependencies:
+
+
+
+```
+
+# Create and Activate python environment
+python -m venv venv_folder
+source venv/bin/activate
+
+# Install required python software
+
+pip install -r requirements.txt
+
+# Generated html documentation
+sphinx-build -b html . build
+
+# Generated pdf documentation
+sphinx-build -b pdf . build
+
+# When finished deactivate the Python environment
+deactivate
+
+```
+
+Documentation is available in `doc/build/html`
+
+### Online Documentation
+
+pFire documentation is available at the following locations:
+
+(Main read the docs documentation)[https://insigneo.github.io/pFIRE/docs.html]
+or
+
+(Insigneo pFIRE github documentation)[https://insigneo.github.io/pFIRE/docs.html#]
+
+
+
+

doc/conf.py

@@ -58,8 +58,8 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+#source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'docs'
@@ -182,6 +182,6 @@
 # -- Options for breathe extension -------------------------------------------
 
 # Set doxygen xml location(s)
-breathe_projects = {"pFIRE_sources" : "../doxygen/xml/"}
+# breathe_projects = {"pFIRE_sources" : "../doxygen/xml/"}
 
-breathe_default_project = "pFIRE_sources"
+# breathe_default_project = "pFIRE_sources"

doc/getting_started/docker.rst

@@ -0,0 +1,36 @@
+===================================
+Using pFIRE in Docker
+===================================
+
+Docker is a software that creates a package (called image) containing an application, its library dependencies and a minimal execution environment (e.g. a minimal Ubuntu distribution). These images can be distributed and run by any Docker software installed on the user machine. In the following are provided the instructions to execute pFIRE on a user machine with Docker. It as been tested on *nix,  OsX  machines and on Windows10 throught the Windows Linux Subsystem.
+
+
+There two ways to use pFIRE in a docker:
+   * download a ready made image from pfire dockerhub channel
+   * build the docker image from the source code	
+
+
+Download a container image ready made from Dockerhub
+--------------------------------------------------------
+
+On the Dockerhub portal are hosted some versions of pFIRE already packaged in a Docker image.
+Follow the instructions on the web page to download and use: 
+
+_PETSc test 
+
+
+Build yourself from dockerfile
+---------------------------------
+If you have installed Docker with command line support you can generate the docker image from the source docker container file.
+Instructions and docker files organised by destination platform are available here:
+
+.. _PETSc: https://www.mcs.anl.gov/petsc/
+
+.. `_pFIRE: docker container source code`: 
+	https://github.com/insigneo-pfire/docker-pfire
+
+
+
+
+
+

doc/getting_started/docker_hub.md

@@ -0,0 +1,58 @@
+# pFIRE on Dockerhub 
+
+Docker is a software that creates a package (called image) containing an application, its library dependencies and a  minimal execution environment (e.g. a minimal Ubuntu distribution). These images can be distributed and run by any Docker software installed on the user machine. 
+In the following are provided the instructions to execute pFIRE on a user machine with Docker. 
+It as been tested on *nix and OsX machines and Windows10 through Windows Linux Subsystem and (PowerShell).
+
+
+### Installation procedure
+* install Docker following instructions:
+https://www.docker.com/products/docker-desktop
+
+* Download docker image
+
+```bash
+docker pull insigneopfire/pfire:v0.4.0
+
+# rename image
+docker image tag insigneopfire/pfire:v0.4.0 pfire_image
+
+```
+
+### Usage instruction binding a local data folder
+
+
+
+Create a folder test_docker containing the input images to be registered  (fixed.png, moved.png).
+
+Create a textual file  (pfire.cfg) containing the pFIRE execution parameters as below 
+
+```
+fixed = fixed.png
+moved = moved.png
+nodespacing = 10
+
+```
+
+Now you can run pFire using Docker:
+
+```bash
+
+ docker run -d -it --name dockerised_pfire -v "$(pwd)"/test_docker:/test_docker  pfire_image
+
+ docker exec -it  -w  /test_docker dockerised_pfire  pfire  pfire.cfg
+
+```
+
+pFIRE should show its running output and results are available in you local test_docker folder.
+
+```bash
+fixed.png  
+moved.png  
+pfire.cfg 
+map.xdmf  
+map.xdmf.h5   
+registered.xdmf  
+registered.xdmf.h5
+```
+

doc/getting_started/index.rst

@@ -10,3 +10,6 @@ using it to register images.
   install
   cli_quickstart
   tutorial
+  docker
+  docker_hub
+

doc/requirements.txt

@@ -0,0 +1,37 @@
+alabaster==0.7.12
+attrs==21.2.0
+Babel==2.9.1
+breathe==4.30.0
+certifi==2020.12.5
+chardet==4.0.0
+docutils==0.16
+httplib2==0.19.1
+idna==2.10
+imagesize==1.2.0
+Jinja2==2.11.3
+markdown-it-py==1.1.0
+MarkupSafe==1.1.1
+mdit-py-plugins==0.2.8
+myst-parser==0.14.0
+packaging==20.9
+plantuml==0.3.0
+Pygments==2.9.0
+pyparsing==2.4.7
+python-json-logger==2.0.1
+pytz==2021.1
+PyYAML==5.4.1
+requests==2.25.1
+snowballstemmer==2.1.0
+Sphinx==3.5.4
+sphinx-autorun==1.1.1
+sphinx-rtd-theme==0.5.2
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==1.0.3
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.4
+sphynx==0.0.3
+structlog==21.1.0
+typing-extensions==3.10.0.0
+urllib3==1.26.4

doc/user_docs/algorithm.rst

@@ -131,7 +131,7 @@ of the gradient information, :math:`\mathbf{{\phi}}` is the same submatrix for e
 map.
 
 The matrix :math:`T` is defined here as the product of the matrices :math:`\mathbf{{G}}` and
-:math:`\mathbf{{\Phi}}`, and it is, in general, non-square.  We therefore create a soluable matrix
+:math:`\mathbf{{\Phi}}`, and it is, in general, non-square.  We therefore create a solvable matrix
 equation from this by multiplying both sides by the transpose :math:`\mathbf{{T}}^t`,
 
 .. math::
@@ -142,7 +142,7 @@ yielding an equation with square matrix :math:`\mathbf{{T}}^t\mathbf{{T}}` which
 standard numerical methods.
 
 Unfortunately :math:`\mathbf{{T}}^t\mathbf{{T}}` is typically singular and so we must apply some
-kind of regularisation to make the problem soluable.  In this case we use the method of Tikhonov
+kind of regularisation to make the problem solvable.  In this case we use the method of Tikhonov
 regularisation, which includes an additional smoothing term in the problem. In this case the
 Laplacian matrix is chosen, adding minimization of the second derivative of the map as the extra
 constraint (:math:`\mathbf{{L}}\bar{A} = 0` and the problem becomes,
@@ -219,7 +219,7 @@ Because of this, pFIRE computes the matrix :math:`\mathbf{{T}}^t\mathbf{{T}}` an
 :math:`\mathbf{{T}}^t(\bar{F} - \bar{M})` directly.  The structure of the final matrix and vector
 are distributed between the various ranks such that each rank computes an equal number of
 components of the final data structure.  For each matrix or vector element, the location of all the
-required image or gradient pixels is determiend and then required values that are not local to the
+required image or gradient pixels is determined and then required values that are not local to the
 rank are communicated using MPI_Alltoall with all ranks communicating at once.
 
 Implementation of the computation can be made more efficient by understanding the structure of the