Remove unneeded READMEs and convert remaining to Markdown

apps/c/airfoil/README.md

@@ -1,5 +1,4 @@
 ### Airfoil
-
 Airfoil is a nonlinear 2D inviscid airfoil code that uses an unstructured grid. It is a finite volume application that
 solves the 2D Euler equations using a scalar numerical dissipation. The algorithm iterates towards the steady state
 solution, in each iteration using a control volume approach – for example the rate at which the mass changes within a
@@ -14,34 +13,27 @@ indirect loops.
 
 Please see airfoil-doc under the ../../doc directory for further OP2 application development details
 
-### Airfoil Application Directory Structure
-
+#### Airfoil Application Directory Structure
 Airfoil has been the main development, testing and benchmarking application in OP2. As such this directory contains
 several versions of Airfoil that demonstrate the use of various OP2 features.
 
-airfoil_plain -- airfoil implemented with user I/O routines (mesh file in ASCI - see ../../apps/mesh_generators
-on how to generate the mesh)
-
-airfoil_hdf5 -- airfoil implemented with OP2 HDF5 routines (mesh file in HDF5, see ASCI to HDF5 file converter)
-
-airfoil_vector -- airfoil user kernels modified to achieve vectorization
-
-airfoil_tempdats -- airfoil use op_decl_temp, i.e. temporary dats in application
+ * `airfoil_plain`: Airfoil implemented with user I/O routines (mesh file in ASCI - see ../../apps/mesh_generators
+on how to generate the mesh).
+ * `airfoil_hdf5`: Airfoil implemented with OP2 HDF5 routines (mesh file in HDF5, see ASCI to HDF5 file converter).
+ * `airfoil_vector`: Airfoil user kernels modified to achieve vectorization.
+ * `airfoil_tempdats`: Airfoil use op_decl_temp, i.e. temporary dats in application.
+ * `compare_results`: Small utility code to compare two files (txt or bin), used to compare the final result from airfoil.
 
-compare_results -- small utility code to compare two files (txt or bin), used to compare the final result from airfoil
-
-### Running the Application and Testing the Results
-
-The input meshes for the application can be generated by using the mesh generators located in :
+#### Running the Application and Testing the Results
+The input meshes for the application can be generated by using the mesh generators located in:
 ```
 OP2-Common/apps/mesh_generators
 ```
-The HDF5 versions of the mesh could be generated by using the convert_mesh application at : 
+The HDF5 versions of the mesh could be generated by using the convert_mesh application at:
 ```
 airfoil/airfoil_hdf5/dp/convert_mesh.cpp
 ```
 
-
 The various parallel versions of Airfoil should be compared against the single-threaded CPU version (also known as the
 reference implementation) to ascertain the correctness of the results. The p_q array holds the final result and as such
 will be the data array to compare. One way to achieve this is to use the following OP2 calls to write the data array to
@@ -52,14 +44,12 @@ op_print_dat_to_txtfile(p_q, "out_grid_seq.dat"); //ASCI
 op_print_dat_to_binfile(p_q, "out_grid_seq.bin"); //Binary
 ```
 
-Then the code in compare.cpp and comparebin.cpp can be used to compare the text file or binary file with the reference
-implementation.
+Then the code in `compare.cpp` and `comparebin.cpp` can be used to compare the text file or binary file with the reference implementation.
 
 Bitwise accuracy can be expected across systems for the double precision version to within the accuracy of machine
 precision. For the single precision version, answers should be very close. A summary print of the rms value of the
 residual is printed out by default every 100 iterations. This in double precision for the first 1000 iterations should
 be exactly:
-
 ```
 100  5.02186e-04
 200  3.41746e-04

doc/README → doc/README.md

@@ -1,19 +1,21 @@
+### Documentation
 To build documentation make sure that the following packages are installed
-
-texlive-science 
+```
+texlive-science
 texlive-latex-extra
 python-pygments
 latex-xcolor
+```
 
-Usually the following will install these :
-
-sudo apt-get install texlive-science texlive-latex-extra latex-xcolor 
+Usually the following will install these:
+```
+sudo apt-get install texlive-science texlive-latex-extra latex-xcolor
 sudo apt-get install python-pygments (or alternatively run: sudo easy_install Pygments)
+```
 
-Then run the shell script build.sh
-
-./script build.sh
+Then run the shell script `build_docs.sh`:
+```
+./build_docs.sh
+```
 
-This will build the C/C++ user documentation, OP2 developer documentation, 
-OP2 MPI (distributed memory) developer documentation and airfoil 
-application developer guide.
+This will build the C/C++ user documentation, OP2 developer documentation, OP2 MPI (distributed memory) developer documentation and airfoil application developer guide.

op2/include/README → op2/include/README.md

@@ -1,33 +1,38 @@
+### Headers
 
-Core components
----------------
+#### Core components
+```
 op_lib_c.h      (includes: op_lib_core.h)
 op_lib_core.h
 op_lib_cpp.h    (includes: op_lib_core.h, op_lib_c.h)
 op_rt_support.h (includes: op_lib_core.h)
+```
 
 
-Sequential layer
-----------------
+#### Sequential layer
+```
 op_seq.h   (auto-generated, includes: op_lib_core.h)
+```
 
-
-OpenMP layer
-------------
+#### OpenMP layer
+```
 op_openmp_rt_support.h (includes: op_rt_support.h)
+```
 
 
-CUDA layer
-----------
+#### CUDA layer
+```
 op_cuda_rt_support.h (includes: op_lib_core.h, op_rt_support.h)
 op_cuda_reduction.h  (has to be kept separate becuase of FORTRAN layer)
+```
 
 
-MPI support
------------
+#### MPI support
+```
 op_hdf5.h            (obsolete?)
 op_lib_mpi.h         (include op_lib_core.h, op_rt_support.h, op_mpi_core.h, op_hdf5.h)
 op_mpi_core.h
 op_mpi_hdf5.h
 op_mpi_seq.h         (includes: op_lib_core.h, op_rt_support.h)
 op_util.h
+```

scripts/README.md

@@ -1,13 +1,8 @@
 ### Scripts
-
-This directory contains various scripts used for testing the build and correct
-execution of OP2 and its example applications. These are provided and commited
-to the repository simply as a referance to any one who is installing and using OP2.
+This directory contains various scripts used for testing the build and correct execution of OP2 and its example applications. These are provided and commited to the repository simply as a referance to any one who is installing and using OP2.
 
 
 #### Files
-
-source_intel, source_pgi -- example files that can be sourced to set the required variables to compile and install with
+ * `source_intel`, `source_pgi`, ...: example files that can be sourced to set the required variables to compile and install with
 Intel and PGI compilers respectively.
-
-test_makefiles.sh -- builds and tests OP2 lib and apps with plain Makefiles (including Fortran libs and apps)
+ * `test_makefiles.sh` -- builds and tests OP2 lib and apps with plain Makefiles (including Fortran libs and apps)

translator/c/README.md

@@ -1,31 +1,26 @@
-###OP2 Code Generators
-
+### C/C++ Code Generators
 This directory contains the OP2 code generators written in python targetting the C/C++ API. The parallelisations and optimisations supported by each generator are as follows:
-
-* op2_gen_seq.py
-* op2_gen_openmp.py - Initial OpenMP code generator
-* op2_gen_openmp_simple.py - Simplified and Optimized OpenMP code generator
-* op2_gen_cuda.py - Optimized for Fermi GPUs
-* op2_gen_cuda_simple - Optimized for Kepler GPUs
-* op2_gen_cuda_simple_hyb.py - generates openmp code as well as cuda code into the same file. Both CPUs and GPUs will then be used to do computations as a hybrid application.
-
-
-###Invoking the Code Generator
-
-Uncomment the parallelization you want to code generate in ops.py. For example for CUDA code generation do:
-
+ * `op2_gen_seq.py`
+ * `op2_gen_openmp.py`: Initial OpenMP code generator.
+ * `op2_gen_openmp_simple.py`: Simplified and Optimized OpenMP code generator.
+ * `op2_gen_cuda.py`: Optimized for Fermi GPUs.
+ * `op2_gen_cuda_simple`: Optimized for Kepler GPUs.
+ * `op2_gen_cuda_simple_hyb.py`: Generates OpenMP code as well as CUDA code into the same file. Both CPUs and GPUs will then be used to do computations as a hybrid application.
+
+#### Invoking the Code Generator
+Uncomment the parallelization you want to code generate in `op2.py`. For example for CUDA code generation do:
 ```
 #op2_gen_seq(str(sys.argv[1]), date, consts, kernels)
 #op2_gen_openmp(str(sys.argv[1]), date, consts, kernels) # Initial OpenMP code generator
 op2_gen_cuda(str(sys.argv[1]), date, consts, kernels,sets) # Optimized for Fermi GPUs
 ```
 
-Make ./op2.py executable
-
-`chmod a+x ./op2.py`
+Make `op2.py` executable
+```
+chmod a+x ./op2.py
+```
 
 Invoke the code generator by supplying the files that contain op_* API calls. Thus for example for Airfoil do the following.
-
 ```
-./ops.py airfoil.cpp
-```
+./op2.py airfoil.cpp
+```

translator/fortran/README.md

@@ -1,40 +1,38 @@
-###OP2 Code Generators
-
-This directory contains the OP2 code generators written in python targetting the FORTRAN API. The parallelisations and optimisations supported by each generator are as follows:
-
-######MPI+SEQ
-* op2_gen_mpiseq.py  - generate host stubs for MPI+SEQ
-* op2_gen_mpiseq3.py - generate host stubs for MPI+SEQ -- optimised by removing the overhead due to fortran c to f pointer setups
-op2_gen_mpivec.py - generate host stubs for MPI+SEQ with intel vectorization optimisations
-
-######OpenMP
-* op2_gen_openmp3.py - optimised by removing the overhead due to fortran c to f pointer setups
-* op2_gen_openmp2.py - version without staging
-* op2_gen_openmp.py  - original version - one that most op2 papers refer to
-
-######CUDA
-* op2_gen_cuda.py
-* op2_gen_cuda_permute.py - permute does a different coloring (permute execution within blocks by color)
-* op2_gen_cudaINC.py   - stages increment data only in shared memory
-* op2_gen_cuda_old.py  - Code generator targettign Fermi GPUs
-
-######If hydra:
-* op2_gen_cuda_hydra() - includes several Hydra specific features
-
-###Invoking the Code Generator
-
-Uncomment the parallelization you want to code generate in op2_fortran.py. For example for CUDA code generation do:
-
+### Fortran Code Generators
+This directory contains the OP2 code generators written in Python targeting the Fortran API. The parallelisations and optimisations supported by each generator are as follows:
+
+##### MPI+SEQ
+ * `op2_gen_mpiseq.py`: Generate host stubs for MPI+SEQ.
+ * `op2_gen_mpiseq3.py`: Generate host stubs for MPI+SEQ -- optimised by removing the overhead due to Fortran C to F pointer setups.
+ * `op2_gen_mpivec.py`: Generate host stubs for MPI+SEQ with intel vectorization optimisations.
+
+##### OpenMP
+ * `op2_gen_openmp3.py`: Optimised by removing the overhead due to Fortran C to F pointer setups.
+ * `op2_gen_openmp2.py`: Version without staging.
+ * `op2_gen_openmp.py`: Original version - one that most OP2 papers refer to.
+
+##### CUDA
+ * `op2_gen_cuda.py`
+ * `op2_gen_cuda_permute.py`: Permute does a different coloring (permute execution within blocks by color).
+ * `op2_gen_cudaINC.py`: Stages increment data only in shared memory.
+ * `op2_gen_cuda_old.py`: Code generator targettign Fermi GPUs.
+
+##### If hydra:
+ * `op2_gen_cuda_hydra()`: Includes several Hydra specific features.
+
+#### Invoking the Code Generator
+Uncomment the parallelization you want to code generate in `op2_fortran.py`. For example for CUDA code generation do:
 ```
 #op2_gen_openmp(str(sys.argv[init_ctr]), date, consts, kernels, hydra)
 op2_gen_cuda(str(sys.argv[1]), date, consts, kernels, hydra)
 ```
 
-Make ./op2_fortran.py executable
-
-`chmod a+x ./op2_fortran.py`
+Make `./op2_fortran.py` executable
+```
+chmod a+x ./op2_fortran.py
+```
 
 Invoke the code generator by supplying the files that contain op_* API calls. Thus for example for Airfoil do the following.
-
 ```
-./op2_fortran.py airfoil.F90
+./op2_fortran.py airfoil.F90
+```