Adding in the documentation directory

README.md

@@ -8,7 +8,7 @@ This repository aims to improve Fortran best practices within UCL and the wider
 - building
 - compiling
 - [debugging](./debugging)
-- documentation
+- [documentation](./documentation)
 - [formatting](./formatting)
 - interfaces
 - libraries

documentation/README.md

@@ -0,0 +1,19 @@
+# Fortran Documentation
+
+Building documentation from your source code has widely been used for a long time, and now commonly used tools like Doxygen work with Fortran.
+
+A number of automated documentation generation projects for Fortran have come and gone over the years, and below are documented a number of them.
+At the top of the list are the recommended and still supported documentation tools.
+
+## Candidate Tools
+
+| Tool | Description | Known issues |
+| ---- | ------ | ----- |
+| **Recommended** |||
+| [Doxygen](https://www.doxygen.nl/) | Commonly used documentation tool for large repositories. Officially supports Fortran with language-specific docblocks. See [doxygen.md](doxygen.md) for details on use. | <ul><li> Examples are somewhat outdated </li><li> Support traditionally has not been great </li></ul> |
+| [FORD](https://github.com/Fortran-FOSS-Programmers/ford) | Created due to Doxygen's lack of Fortran compatability, FORtran Documentater (FORD) is an independent automatic documenter for modern Fortran. See [ford.md](ford.md) for details on use. | <ul><li> Not the healthiest repository </li><li> Not as feature rich as Doxygen (in principle) </ul> |
+| **Dead projects** | | |
+| [ROBODoc](https://rfsber.home.xs4all.nl/Robo/) | Automatic parsing of any comment-enabled language into various output formats | <ul><li>Last updated 2021</li><li> Various links no longer work </li><li> Cannot actually extract information correctly from Fortran </li></ul> |
+| [Doctran](https://github.com/CPardi/Doctran) | Cross-platform documentation generator specifically designed for Fortran | <ul><li> Last updated 9 years ago </li><li> Homepage examples et al no longer exist </li></ul> |
+| [f90tohtml](https://code.google.com/archive/p/f90tohtml/) | | Last revision 2009 |
+| [f90doc](https://fortranwiki.org/fortran/show/f90doc) | The basis for FORD | Last revision 2005 |

documentation/doxygen.md

@@ -0,0 +1,57 @@
+# [Doxygen](https://www.doxygen.nl/)
+
+The Doxygen tool is a widely-used tool for automatically generating documentation from a codebase.
+It 
+
+## Prerequisites
+
+Min reqs:
+
+- Python >= 2.7
+- GNU tools `flex`, `bison`, `libiconv` and `GNU make`
+- cmake >= 3.14
+
+For all features:
+- Qt >= 5.14
+- A `latex` distribution
+- [Graphvix](https://www.graphviz.org/) >= 2.38
+- [Ghostscipt](https://www.ghostscript.com/)
+
+## Installation
+
+Installation is done from source via the Doxygen [download page](https://www.doxygen.nl/download.html).
+
+Download the latest version for your operating system from that page, and follow the extensive [installation instructions](https://www.doxygen.nl/manual/install.html) provided by Doxyden.
+
+## Use
+
+The [User Manual](https://www.doxygen.nl/manual/index.html) is well documented and explains how the documentation keywords are read from docstring blocks.
+
+There is a brief note on the specific comment style required for Fortran comments in the [Documenting the code](https://www.doxygen.nl/manual/docblocks.html#fortranblocks) section.
+A comment block readable by `Doxygen` begins with `!>` or `!<`, and can be continued over multiple lines with `!!` or `!>`.
+The usual Doxygen keywords then apply within these blocks.
+
+An example subroutine would look like:
+
+```Fortran
+!> @brief    Write results to an output file
+!! @details  Writes the generated mesh to a specified output file
+!!
+!! @param num_nodes        Number of nodes to write to the output file
+!! @param num_elements     Number of elements to write to the output file
+!! @param element_to_node  Values of the elements to write
+!! @param coordinates      Co-ordinates of the node points to write
+!! @param nodal_value_of_f Nodal value of f
+!! @param file_io          Output file
+subroutine write_output_file(num_nodes,num_elements,element_to_node,coordinates,nodal_value_of_f,file_io)
+	implicit none
+
+	integer, intent(in) :: num_nodes,num_elements,element_to_node(3,mxp),file_io
+	real, intent(in)    :: nodal_value_of_f(mxp), coordinates(2, mxp)
+	!...
+end subroutine
+```
+
+### TODO
+
+Actually implement Doxygen into our repo and check the output...

documentation/ford.md

@@ -0,0 +1,35 @@
+# [FORD](https://github.com/Fortran-FOSS-Programmers/ford)
+
+FORtran Documenter (FORD) is an automatic documentation generater designed for Fortran.
+
+Originally conveived due to Doxygen's historical lack of Fortran support, FORD has turned into a well established and feature-rich documentation project.
+See [the FORD repository](https://github.com/Fortran-FOSS-Programmers/ford) for a full description of the features available.
+
+TODO list some of the useful bits we're interested in here/are unique from Doxygen?
+
+## Installation
+
+Installation (and automatic handling of dependencies) can be done through pip:
+
+```sh
+pip install ford
+```
+
+Installation is also available through Homebrew with the following commands:
+
+```sh
+brew update
+brew install FORD
+```
+
+There is also a spack pacakge available to install FORD:
+
+```sh
+spack install py-ford
+```
+
+## Use
+
+I would like to have some examples here, which could be in a sub-directory. 
+Next Tooling Day, I suppose!
+Or if anyone else wants to contribute them...