Add Long-form API documentation (#53)

* Add docs gh workflow.

* Add basif FTorch.md for FORD.

* Update docs workflow to build site on branch.

* Update docs workflow to build site on branch.

* Update docs workflow to have different branch names.

* Add additional page drafts to docs.

* Add to documentation - slides, license, cmake.

* Restructure other docs.

* Add transpose docs [WIP].

* Add transpose docs [WIP].

* Update docs workflow following review by @jwallwork23. Still builds from this branch for now.

* Update install docs following review by @jwallwork23 and clarify Windows instructions.

* Update docs page on transposition of data and torch_tensor_from_array/blob.

* Move 'Other Documentation' to 'User Guide'.

* Update empty examples page with generic example from the main README and links to worked examples.

* Update main page with latest talks and projects.

* Update workflow to build docs for main rather than this branch in anticipation of merging.

* Prune README by linking to online documentation.

* Minor updates to README for TOC and typos.

* Add Fortran snippet to top of README to showcase FTorch.

* Consisten spelling of CMake and FTorch in examples.

.github/workflows/build_docs.yml

@@ -0,0 +1,55 @@
+# workflow to build and deploy FORD docs for FTorch
+
+name: BuildDocs
+
+# Controls when the workflow will run
+on:
+  # Triggers the workflow on push or pull request events but only for the "main" branch
+  push:
+    branches: [ "main"]
+  pull_request:
+    branches: [ "main" ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Workflow run - one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build-docs"
+  build-docs:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ford
+
+      - name: Build docs with FORD
+        run: ford FTorch.md
+
+      - name: Test docs build
+        if: github.ref != 'refs/heads/main'
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: docs-test # The branch the action should deploy to.
+          folder: doc      # The folder the action should deploy.
+          dry-run: true    # Don't actually push to pages, just test if we can
+
+      - name: Deploy Documentation for main
+        if: github.ref == 'refs/heads/main'
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages # The branch the action should deploy to.
+          folder: doc      # The folder the action should deploy.

.gitignore

@@ -1,3 +1,6 @@
+# Documentation files
+/doc/*
+
 # Prerequisites
 *.d
 

FTorch.md

@@ -0,0 +1,76 @@
+---
+project: FTorch
+summary: A library for coupling (Py)Torch machine learning models to Fortran
+author: ICCS Cambridge
+license: mit
+github: https://github.com/Cambridge-ICCS
+project_github: https://github.com/Cambridge-ICCS/FTorch
+page_dir: pages
+src_dir: ./src
+         ./utils
+output_dir: ./doc
+exclude_dir: **/build*
+extra_filetypes: c   //
+                 cpp //
+                 h //
+                 py  #
+sort: alpha
+source: true
+graph: true
+externalize: true
+md_extensions: markdown.extensions.toc
+               markdown.extensions.tables
+               markdown.extensions.fenced_code
+---
+
+--------------------
+
+[TOC]
+
+Brief description
+-----------------
+
+It is desirable to be able to run machine learning (ML) models directly in Fortran.
+ML models are often trained in some other language (say, Python) using a popular frameworks (say, PyTorch) and saved.
+We want to run inference on this model without having to call a Python executable.
+To achieve this we use the existing Torch C++ interface, libtorch.
+
+FTorch provides a library enabling a user to directly couple their PyTorch models to Fortran code.
+There are also installation instructions for the library and examples of performing coupling.
+
+We support running on both CPU and GPU, and have tested the library on UNIX and Windows based operating systems
+
+Presentations
+-------------
+
+The following presentations contain information about FTorch:
+
+* Reducing the overheads for coupling PyTorch machine learning models to Fortran\
+  ML & DL Seminars, LSCE, IPSL, Paris - November 2023\
+  [Slides](IPSL_FTorch/IPSL_FTorch.html) - [Recording](https://www.youtube.com/watch?v=-NJGuV6Rz6U)
+* Reducing the Overhead of Coupled Machine Learning Models between Python and Fortran\
+  RSECon23, Swansea - September 2023\
+  [Slides](https://jackatkinson.net/slides/RSECon23/RSECon23.html) - [Recording](https://www.youtube.com/watch?v=Ei6H_BoQ7g4&list=PL27mQJy8eDHmibt_aL3M68x-4gnXpxvZP&index=33)
+
+License
+-------
+
+The FTorch source code, related files and documentation are
+distributed under an [MIT License which can be viewed here](page/LICENSE.html).
+
+
+Projects using FTorch
+---------------------
+
+The following projects make use of FTorch.  
+If you use our library in your work please let us know.
+
+* [M2LInES CAM-ML](https://github.com/m2lines/CAM-ML)\
+  Using FTorch to couple a neural net parameterisation of convection to the CAM
+  atmospheric model in CESM.
+* [DataWave CAM-GW](https://github.com/DataWaveProject/CAM/)\
+  Using FTorch to couple neural net parameterisations of gravity waves to the CAM
+  atmospheric model in CESM.
+* [MiMA Machine Learning](https://github.com/DataWaveProject/MiMA-machine-learning)\
+  Using FTorch to couple a neural net parameterisation of gravity waves to the MiMA
+  atmospheric model.