Update links in several pages

rfj82982 · rfj82982 · commit 8665a8bceac7 · 2023-07-26T14:51:45.000+01:00
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -2,6 +2,7 @@
    sphinx-quickstart on Wed Feb 15 14:31:32 2023.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
+
 =========================================================
 Welcome to the documentation for the 2DECOMP&FFT library!
 =========================================================
diff --git a/docs/source/pages/contributing.rst b/docs/source/pages/contributing.rst
@@ -1,6 +1,6 @@
-=============
+============
 Contributing
-=============
+============
 
 Overview of the contribution process
 ====================================
@@ -43,55 +43,78 @@ bug not currently referenced by an existing issue, or have an idea on
 how to improve a part of 2DECOMP&FFT, please open a new item on the issue
 tracker before opening a pull request.
 
-# Contributing
+Contributing
+============
+
+1. You want to contribute but have no idea how ? Please refer to the section :ref:`labelGetStarted`.
+2. You have identified a bug ? Please refer to the section :ref:`labelBug`.
+3. You have improved a part of the code or have developed a new functionality ? 
+   Please refer to the section :ref:`labelAdvanced`.
 
-1. You want to contribute but have no idea how ? Please refer to the [Get started](#get-started) section.
-2. You have identified a bug ? Please refer to the [Bug](#bug) section.
-3. You have improved a part of the code or have developed a new functionality ? Please refer to the [advanced](#advanced-contribution) section.
+.. _labelGetStarted:
 
-## Get started
+Get started
+___________
 
-The recommended strategy to contribute is to start with a [discussion](https://github.com/2decomp-fft/2decomp-fft/discussions) or to pick an existing issue.
-To modify or experiment with the code, fork the 2decomp github repository and commit changes in a dedicated branch of your fork.
-When the modification is ready for review, one can open a pull request as described in the [advanced](#advanced-contribution) section below.
+The recommended strategy to contribute is to start with a 
+`discussion <https://github.com/2decomp-fft/2decomp-fft/discussions>`_ 
+or to pick an 
+`existing issue <https://github.com/2decomp-fft/2decomp-fft/issues>`_.
+To modify or experiment with the code, fork the 2DECOMP&FFT github repository  
+and commit changes in a dedicated branch of your fork.
+When the modification is ready for review, one can open a pull request as described in the section 
+:ref:`labelAdvanced` below.
 
-## Bug
+.. _labelBug:
 
-It appears that you have identified a bug in the 2decomp library.
-If you are not sure this is really a bug in the library, you should go to the [discussions](https://github.com/2decomp-fft/2decomp-fft/discussions) section and open a new discussion.
+Bug
+___
+
+It appears that you have identified a bug in the 2DECOMP&FFT library.
+If you are not sure this is really a bug in the library, 
+you should go to the 
+`discussions <https://github.com/2decomp-fft/2decomp-fft/discussions>`_ 
+section and open a new discussion.
 Otherwise, follow the steps below.
 
-Firstly, try to reproduce the error with a debug build of the library, a small problem size and a small number of MPI ranks.
+Firstly, try to reproduce the error with a debug build of the library, 
+a small problem size and a small number of MPI ranks.
 It makes bug-hunting much easier.
 Unfortunately, this is not always possible.
 Please note that for a debug build, the log contains all the environment variables.
 Use it to hunt the bug but think twice before sharing it as it can expose sensitive and personal information.
 At least, please try to reproduce the bug on another machine with another compiler.
 
-Secondly, if you have modified the source code of the 2decomp library, you must reproduce the bug without the modifications in 2decomp.
+Secondly, if you have modified the source code of the 2DECOMP&FFT library, 
+you must reproduce the bug without the modifications in 2DECOMP&FFT.
 The development team can only provide support for sections of code available in the present repository.
 
 Thirdly, you must provide a minimal working example.
-The program using 2decomp and exposing the bug should be relatively small.
+The program using 2DECOMP&FFT and exposing the bug should be relatively small.
 The development team will not provide support if the program exposing the bug is very long.
 The programs available in the examples section are a good starting point for a minimal working example, ideally you could contribute the minimal working example to the existing examples.
 
 At this stage, you probably did your best to simplify the problem at hand.
 Open an issue and select the bug report template.
-Provide a meaningful title, do your best to complete all the sections of the template and provide the version of the compiler, the version of the MPI / FFT library, ...
+Provide a meaningful title, do your best to complete all the sections of the template 
+and provide the version of the compiler, the version of the MPI / FFT library, ...
 If you think you have a fix for the bug, please expose it inside the issue.
 It is recommended to wait for feedback before opening a pull request.
 
-## Advanced contribution
+.. _labelAdvanced:
+
+Advanced contribution
+_____________________
 
 One should read this section before opening a pull request.
 To fix a bug, please open an issue and use the bug report template first.
 To improve a part of the code or develop a new functionality, please open an issue and use the feature request template first.
-If you are not sure about your contribution, open a [discussion](https://github.com/2decomp-fft/2decomp-fft/discussions) first.
+If you are not sure about your contribution, open a 
+`discussion <https://github.com/2decomp-fft/2decomp-fft/discussions>`_ first.
 This helps raise awareness of the work and prevents repeated effort from occurring.
 
-The code in a pull-request should be formatted using the `fprettify` program.
-See the code sample in the `scripts` folder.
+The code in a pull-request should be formatted using the ``fprettify`` program.
+See the code sample in the ``scripts`` folder.
 
 Pull requests must be focused, small, coherent and have a detailed description.
 The longer the pull request, the harder the review.
diff --git a/docs/source/pages/installation.rst b/docs/source/pages/installation.rst
@@ -39,7 +39,7 @@ The value provided with the environment variable must be a positive integer belo
 Two ``BUILD_TARGETS`` are available namely ``mpi`` and ``gpu``.  
 For the ``mpi`` target no additional options should be required, 
 whereas for ``gpu`` extra options are necessary at the configure stage. 
-Please see section [GPU Compilation](#gpu-compilation)
+Please see :ref:`labelGPU` section. 
 
 Once the build system has been configured, you can build 2DECOMP&FFT by running
 
@@ -49,9 +49,10 @@ Once the build system has been configured, you can build 2DECOMP&FFT by running
 
 appending ``-v`` will display additional information about the build, such as compiler flags.
 
-After building the library can be tested. Please see section [Testing and examples](#testing-and-examples)
+After building the library can be tested using ``ctest``. Please see :ref:`labelTest` section
 
-Options can be added to change the level of verbosity. Finally, the build library can be installed by running 
+Options can be added to change the level of verbosity. 
+Finally, the build library can be installed by running 
 
 :: 
   
@@ -65,7 +66,8 @@ The default location for **libdecomp2d.a** is
 
 unless the variable ``CMAKE_INSTALL_PREFIX`` is modified.
 
-The module files generated by the build process will similarly be installed to ``$path_to_build_directory/opt/install``, 
+The module files generated by the build process will similarly be installed to 
+``$path_to_build_directory/opt/install``, 
 users of the library should add this to the include paths for their program.
 
 As indicated above, by default a static **libdecomp2d.a** will be compiled, 
@@ -85,6 +87,34 @@ Occasionally a clean build is required, this can be performed by running
    
      cmake --build $path_to_build_directory --target clean
 
+.. _labelTest:
+
+Testing and examples
+====================
+
+By default building of the tests is deactivated.
+To activate the testing the option ``-DBUILD_TESTING=ON`` can be added or
+alternativey the option can be activated in the GUI interface ``ccmake``.
+After building the library can be tested by running
+
+::
+
+  ctest --test-dir $path_to_build_directory
+
+which uses the ``ctest`` utility. By default tests are performed in serial,
+but more than 1 rank can be used by setting ``MPIEXEC_MAX_NUMPROCS`` under ``ccmake`` utility.
+It is also possible to specify the decomposition by setting
+``prow`` and ``pcol`` parameters at the configure stage or using ``ccmake``.
+During the configure stage users should ensure that the number of MPI tasks ``MPIEXEC_MAX_NUMPROCS``
+is equal to the product of *pcol* times *prow*.
+Mesh resolution can also be imposed using the parameters ``NX``, ``NY`` and ``NZ``.
+
+For the GPU implementation please be aware that it is based on a single MPI rank per GPU.
+Therefore, to test multiple GPUs, use the maximum number of available GPUs
+on the system/node and not the maximum number of MPI tasks.
+
+.. _labelGPU: 
+
 GPU compilation
 ===============
 
@@ -101,7 +131,7 @@ To properly configure for GPU build the following needs to be used
 Note, further configuration can be performed using ``ccmake``, 
 however the initial configuration of GPU builds must include the ``-DBUILD_TARGET=gpu`` flag as shown above.
 
-By default CUDA aware MPI will be used together with `cuFFT` for the FFT library. The configure will automatically look for the GPU architecture available on the system. If you are building on a HPC system please use a computing node for the installation. Useful variables to be added are 
+By default CUDA aware MPI will be used together with ``cudaFFT`` for the FFT library. The configure will automatically look for the GPU architecture available on the system. If you are building on a HPC system please use a computing node for the installation. Useful variables to be added are 
 
  - ``-DENABLE_NCCL=yes`` to activate the NCCL collectives
  - ``-DENABLE_MANAGED=yes`` to activate the automatic memory management form the NVHPC compiler
@@ -240,11 +270,14 @@ _____________________
 FFTW
 ^^^^
 
-The library [fftw](http://www.fftw.org/index.html) can be used as a backend for the FFT engine. 
-The version 3.3.10 was tested, is supported and can be downloaded [here](http://www.fftw.org/download.html). 
+The library `FFTW <http://www.fftw.org/index.html>`_ can be used as a backend for the FFT engine. 
+The version 3.3.10 was tested, is supported and can be downloaded 
+`here [FFTW Download] <http://www.fftw.org/download.html>`_. 
 Please note that one should build fftw and decomp2d against the same compilers. 
-For build instructions, please check [here](http://www.fftw.org/fftw3_doc/Installation-on-Unix.html). 
-Below is a suggestion for the compilation of the library in double precision (add ``--enable-single`` for a single precision build):
+For build instructions, please check 
+`the instructions <http://www.fftw.org/fftw3_doc/Installation-on-Unix.html>`_. 
+Below is a suggestion for the compilation of the library in double precision 
+(add ``--enable-single`` for a single precision build):
 
 :: 
 
@@ -256,7 +289,8 @@ Below is a suggestion for the compilation of the library in double precision (ad
   make -j check
   make install
 
-Please note that the resulting build is not compatible with CMake (https://github.com/FFTW/fftw3/issues/130). 
+Please note that the resulting build is not compatible with CMake 
+`see here <https://github.com/FFTW/fftw3/issues/130>`_.
 As a workaround, one can open the file `/path/to/fftw3/install/lib/cmake/fftw3/FFTW3Config.cmake` and comment the line
 
 ::
@@ -280,9 +314,12 @@ Note the legacy **fftw** interface lacks interface definitions and will fail whe
 Caliper
 ^^^^^^^
 
-The library [caliper](https://github.com/LLNL/Caliper) can be used to profile the execution of the code. The version 2.9.1 was tested and is supported, 
-version 2.8.0 has also been tested and is still expected to work. Please note that one must build caliper and decomp2d against the same C/C++/Fortran compilers and MPI libray. For build instructions, 
-please check [here](https://github.com/LLNL/Caliper#building-and-installing) and [here](https://software.llnl.gov/Caliper/CaliperBasics.html#build-and-install). 
+The library `caliper <https://github.com/LLNL/Caliper>`_ can be used to profile the execution of the code. 
+The version 2.9.1 was tested and is supported, 
+version 2.8.0 has also been tested and is still expected to work. 
+Please note that one must build caliper and decomp2d against the same C/C++/Fortran compilers and MPI libray. For build instructions, 
+please check `the relative GitHub page <https://github.com/LLNL/Caliper#building-and-installing>`_ 
+and `here <https://software.llnl.gov/Caliper/CaliperBasics.html#build-and-install>`_. 
 Below is a suggestion for the compilation of the library using the GNU compilers:
 
 ::
