From 18d34b8ad3e5f5017dfcc0243d37bb35c6dc0577 Mon Sep 17 00:00:00 2001 From: Duncan Leggat Date: Tue, 26 Aug 2025 15:59:40 +0100 Subject: [PATCH 1/7] First parse of readme for documentation --- documentation/README.md | 15 +++++++++++++++ documentation/README.md~ | 17 +++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 documentation/README.md create mode 100644 documentation/README.md~ diff --git a/documentation/README.md b/documentation/README.md new file mode 100644 index 0000000..2a70b56 --- /dev/null +++ b/documentation/README.md @@ -0,0 +1,15 @@ +# 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. + +## 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 | | +| [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 | | +| **Dead projects** | | | +| [ROBODoc](https://rfsber.home.xs4all.nl/Robo/) | Automatic parsing of any comment-enabled language into various output formats | | +| [Doctran](https://github.com/CPardi/Doctran) | Cross-platform documentation generator specifically designed for Fortran | | +| [f90tohtml](https://code.google.com/archive/p/f90tohtml/) | | Last revision 2009 | +| [f90doc](https://fortranwiki.org/fortran/show/f90doc) | | Last revision 2005 | diff --git a/documentation/README.md~ b/documentation/README.md~ new file mode 100644 index 0000000..83c9f68 --- /dev/null +++ b/documentation/README.md~ @@ -0,0 +1,17 @@ +# 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. + +## 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 | | +| [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 | | +| **Other options** | | | +| +| **Dead projects** | | | +| [ROBODoc](https://rfsber.home.xs4all.nl/Robo/) | Automatic parsing of any comment-enabled language into various output formats | | +| [Doctran](https://github.com/CPardi/Doctran) | Cross-platform documentation generator specifically designed for Fortran | | +| [f90tohtml](https://code.google.com/archive/p/f90tohtml/) | | Last revision 2009 | +| [f90doc](https://fortranwiki.org/fortran/show/f90doc) | | Last revision 2005 | From 6ced6fef5623ba44d0b88d319baa9bb1a21ef83a Mon Sep 17 00:00:00 2001 From: Duncan Leggat Date: Tue, 26 Aug 2025 16:00:17 +0100 Subject: [PATCH 2/7] Adding in a Doxygen markdown --- documentation/README.md | 2 +- documentation/doxygen.md | 57 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 documentation/doxygen.md diff --git a/documentation/README.md b/documentation/README.md index 2a70b56..1eec218 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -6,7 +6,7 @@ Building documentation from your source code has widely been used for a long tim | Tool | Description | Known issues | | **Recommended** | | | -| [Doxygen](https://www.doxygen.nl/) | Commonly used documentation tool for large repositories. Officially supports Fortran with language-specific docblocks | | +| [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. | | | [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 | | | **Dead projects** | | | | [ROBODoc](https://rfsber.home.xs4all.nl/Robo/) | Automatic parsing of any comment-enabled language into various output formats | | diff --git a/documentation/doxygen.md b/documentation/doxygen.md new file mode 100644 index 0000000..d3c32cc --- /dev/null +++ b/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... From 48d97bd4ee5c2dcdbb870e7c85b9495f2c2e2121 Mon Sep 17 00:00:00 2001 From: Duncan Leggat Date: Tue, 26 Aug 2025 16:25:54 +0100 Subject: [PATCH 3/7] Adding in FORD --- documentation/README.md | 9 ++++++--- documentation/ford.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+), 3 deletions(-) create mode 100644 documentation/ford.md diff --git a/documentation/README.md b/documentation/README.md index 1eec218..1001ed5 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -2,14 +2,17 @@ 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. |
  • Examples are somewhat outdated
  • Support traditionally has not been great
| -| [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 |
  • Not the healthiest repository
  • Not as feature rich as Doxygen (in principle)
| +| [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. |
  • Not the healthiest repository
  • Not as feature rich as Doxygen (in principle)
| | **Dead projects** | | | -| [ROBODoc](https://rfsber.home.xs4all.nl/Robo/) | Automatic parsing of any comment-enabled language into various output formats |
  • Last updated 2021
  • Various links no longer work
| +| [ROBODoc](https://rfsber.home.xs4all.nl/Robo/) | Automatic parsing of any comment-enabled language into various output formats |
  • Last updated 2021
  • Various links no longer work
  • Cannot actually extract information correctly from Fortran
| | [Doctran](https://github.com/CPardi/Doctran) | Cross-platform documentation generator specifically designed for Fortran |
  • Last updated 9 years ago
  • Homepage examples et al no longer exist
| | [f90tohtml](https://code.google.com/archive/p/f90tohtml/) | | Last revision 2009 | -| [f90doc](https://fortranwiki.org/fortran/show/f90doc) | | Last revision 2005 | +| [f90doc](https://fortranwiki.org/fortran/show/f90doc) | The basis for FORD | Last revision 2005 | diff --git a/documentation/ford.md b/documentation/ford.md new file mode 100644 index 0000000..4029fd2 --- /dev/null +++ b/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... From be17b78f9fa6a1b69ae57582f182f9293be7d5f8 Mon Sep 17 00:00:00 2001 From: Duncan Leggat <133978460+dleggat@users.noreply.github.com> Date: Tue, 26 Aug 2025 16:32:33 +0100 Subject: [PATCH 4/7] Fixing table formatting --- documentation/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/README.md b/documentation/README.md index 1001ed5..555ff99 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -8,7 +8,8 @@ At the top of the list are the recommended and still supported documentation too ## Candidate Tools | Tool | Description | Known issues | -| **Recommended** | | | +| ---- | ------ | ----- | +| **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. |
  • Examples are somewhat outdated
  • Support traditionally has not been great
| | [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. |
  • Not the healthiest repository
  • Not as feature rich as Doxygen (in principle)
| | **Dead projects** | | | From 2401545677d68f88a10b5a957d884b4391fc5f4d Mon Sep 17 00:00:00 2001 From: Duncan Leggat Date: Tue, 26 Aug 2025 16:33:08 +0100 Subject: [PATCH 5/7] Removing extraneous file --- documentation/README.md~ | 17 ----------------- 1 file changed, 17 deletions(-) delete mode 100644 documentation/README.md~ diff --git a/documentation/README.md~ b/documentation/README.md~ deleted file mode 100644 index 83c9f68..0000000 --- a/documentation/README.md~ +++ /dev/null @@ -1,17 +0,0 @@ -# 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. - -## 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 |
  • Examples are somewhat outdated
  • Support traditionally has not been great
| -| [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 |
  • Not the healthiest repository
  • Not as feature rich as Doxygen (in principle)
| -| **Other options** | | | -| -| **Dead projects** | | | -| [ROBODoc](https://rfsber.home.xs4all.nl/Robo/) | Automatic parsing of any comment-enabled language into various output formats |
  • Last updated 2021
  • Various links no longer work
| -| [Doctran](https://github.com/CPardi/Doctran) | Cross-platform documentation generator specifically designed for Fortran |
  • Last updated 9 years ago
  • Homepage examples et al no longer exist
| -| [f90tohtml](https://code.google.com/archive/p/f90tohtml/) | | Last revision 2009 | -| [f90doc](https://fortranwiki.org/fortran/show/f90doc) | | Last revision 2005 | From 790f003e8c357a03470f1729dc89d2661abf049d Mon Sep 17 00:00:00 2001 From: Duncan Leggat <133978460+dleggat@users.noreply.github.com> Date: Tue, 26 Aug 2025 16:34:51 +0100 Subject: [PATCH 6/7] Adding link to documentation directory --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dad3cee..bfe9ccc 100644 --- a/README.md +++ b/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 From a58ed71f47a4523b71e408584fe53a94450dd795 Mon Sep 17 00:00:00 2001 From: Duncan Leggat <133978460+dleggat@users.noreply.github.com> Date: Fri, 10 Oct 2025 10:47:40 +0100 Subject: [PATCH 7/7] Update documentation/ford.md Fixing typo Co-authored-by: Connor Aird --- documentation/ford.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/ford.md b/documentation/ford.md index 4029fd2..93b9819 100644 --- a/documentation/ford.md +++ b/documentation/ford.md @@ -22,7 +22,7 @@ brew update brew install FORD ``` -There is also a spack pacakge available to install FORD: +There is also a spack package available to install FORD: ```sh spack install py-ford