Add documentation

.github/workflows/docs.yaml

@@ -0,0 +1,58 @@
+#
+# Distributed Linear Algebra with Future (DLAF)
+#
+# Copyright (c) 2018-2024, ETH Zurich
+# All rights reserved.
+#
+# Please, refer to the LICENSE file in the root directory.
+# SPDX-License-Identifier: BSD-3-Clause
+#
+
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+      - '**' # TODO: Remove when done testing!
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  # Pull requests to main trigger this workflow
+  # However, the deployment is skipped (see check on github.ref)
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Configure
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ford
+      - name: Build (main)
+        run: |
+          python -m ford --output_dir ghpages DLA-Future-Fortran.md
+          echo {{ github.repository }}
+      - name: Publish (main)
+        #if: "github.repository == 'eth-cscs/DLA-Future-Fortran' && github.ref == 'refs/heads/main'"
+        if: "github.repository == 'RMeli/DLA-Future-Fortran'"
+        run: |
+          COMMIT_MSG=`git log -n 1 --pretty=format:%s`
+          mv ghpages main
+          git config user.name "Documentation CI Action" && git config user.email "[email protected]"
+          git fetch --no-tags --depth=1 origin +refs/heads/docs-ghpages:refs/heads/docs-ghpages
+          git symbolic-ref HEAD refs/heads/docs-ghpages && git reset
+          git add main && git commit --allow-empty -m "Documentation: $COMMIT_MSG" && git push --set-upstream origin docs-ghpages
+      - name: Publish (tag)
+        if: "github.repository == 'eth-cscs/DLA-Future-Fortran' && startsWith(github.ref, 'refs/tags/v')"
+        run: |
+          TAG=${{ github.ref_name }}
+          mv ghpages $TAG
+          git config user.name "Documentation CI Action" && git config user.email "[email protected]"
+          git fetch --no-tags --depth=1 origin +refs/heads/docs-ghpages:refs/heads/docs-ghpages
+          git symbolic-ref HEAD refs/heads/docs-ghpages && git reset
+          git add $TAG && git commit --allow-empty -m "Documentation: add doccumentation for $TAG" && git push --set-upstream origin docs-ghpages

.gitignore

@@ -21,3 +21,6 @@ build-*
 *~
 *.swp
 *.orig
+
+# Documentation
+documentation

DLA-Future-Fortran.md

@@ -0,0 +1,128 @@
+---
+project: DLA-Future-Fortran
+summary: Fortan interface for DLA-Future
+project_github: https://github.com/eth-cscs/DLA-Future-Fortran
+project_download: https://github.com/eth-cscs/DLA-Future-Fortran/releases
+print_creation_date: true
+output_dir: documentation
+media_dir: docs
+doc_license: bsd
+---
+
+[DLA-Future-Fortran] is a [Fortran] interface for [DLA-Future], a task-based linear algebra library providing GPU-enabled distributed eigensolver. [DLA-Future] is based on the [pika] library for concurrency and parallelism, and supports both [Nvidia] and [AMD] GPUs.
+
+## Usage
+
+### Initialization and finalization
+
+Before calling any [DLA-Future] routine, the library (and the underlying [pika] runtime) need to be initialized:
+
+```Fortran
+call dlaf_initialize()
+```
+
+[DLA-Future] should be finalized when it is no longer needed:
+
+```Fortran
+call dlaf_finalize()
+```
+
+## Grid initialization 
+
+[DLA-Future] needs to know how a matrix is distributed. A [DLA-Future] grid can be created directly on top of a [BLACS] grid, using the corresponding [BLACS] context:
+
+```Fortran
+! blacs_context is an existing BLACS context
+call dlaf_create_grid_from_blacs(blacs_context)
+```
+
+When a grid is no longer needed, it can be freed:
+
+```Fortran
+! blacs_context is an existing BLACS context
+call dlaf_free_grid(blacs_context)
+```
+
+### ScaLAPACK drop-in
+
+[DLA-Future-Fortran] can be used as a [ScaLAPACK] drop-in. [DLA-Future] takes a subset of [ScaLAPACK] arguments. For example, workspaces are managed internally in [DLA-Future].
+
+#### Example: Hermitian generalized eigensolver
+
+The following is an example of how a code using [ScaLAPACK]'s hermitian generalized eigensolver can be adapted to use [DLA-Future] instead:
+
+```diff
+ call mpi_init_thread(...)
++call dlaf_initialize()
+ call blacs_get(0, 0, blacs_context)
+ call blacs_gridinit(blacs_context, ...)
++call dlaf_create_grid_from_blacs(blacs_context)
+
+ ! ...
+
+-! Workspaces setup (work, rwork, iwork)
+
+-call pzheevd('V', 'L', n, a, 1, 1, desca, w, z, 1, 1, descz, work, lwork, rwork, lrwork, iwork, liwork, info)
++call call dlaf_pzheevd('L', n, a, 1, 1, desca, w, z, 1, 1, descz, info)
+
+-! Workspaces cleanup (work, rwork, iwork)
+
+ ! ...
+
++call dlaf_free_grid(blacs_context)
+ call blacs_gridexit(blacs_context)
++call dlaf_finalize()
+ call mpi_finalize(...)
+```
+
+## Citation
+
+### DLA-Future Conference Paper
+
+If you are using [DLA-Future-Fortran], please cite the following conference paper in addition to the [DLA-Future-Fortran] and the [DLA-Future] repositories:
+
+```
+@InProceedings{10.1007/978-3-031-61763-8_13,
+    author="Solc{\`a}, Raffaele
+        and Simberg, Mikael
+        and Meli, Rocco
+        and Invernizzi, Alberto
+        and Reverdell, Auriane
+        and Biddiscombe, John",
+    editor="Diehl, Patrick
+        and Schuchart, Joseph
+        and Valero-Lara, Pedro
+        and Bosilca, George",
+    title="DLA-Future: A Task-Based Linear Algebra Library Which Provides a GPU-Enabled Distributed Eigensolver",
+    booktitle="Asynchronous Many-Task Systems and Applications",
+    year="2024",
+    publisher="Springer Nature Switzerland",
+    address="Cham",
+    pages="135--141",
+    isbn="978-3-031-61763-8"
+}
+```
+
+## Acknowledgements
+
+The development of [DLA-Future-Fortran] is supported by the following organizations:
+
+* [CSCS]: Swiss National Supercomputing Center
+* [ETH Zurich]: Swiss Federal Institute of Technology Zurich
+* [PASC]: Platform for Advanced Scientific Computing
+
+![CSCS](|media|/images/logo-cscs.jpg){: style="text-align: center" height=75}
+![ETHZ](|media|/images/logo-eth.svg){: style="text-align: center" height=75}
+![PASC](|media|/images/logo-pasc.png){: style="text-align: center" height=75}
+
+[AMD]: https://www.amd.com/en.html
+[BLACS]: https://www.netlib.org/blacs/
+[CSCS]: https://www.cscs.ch
+[DLA-Future-Fortran]: https://github.com/eth-cscs/DLA-Future-Fortran
+[DLA-Future]: https://github.com/eth-cscs/DLA-Future
+[ETH Zurich]: https://ethz.ch/en.html
+[Fortran]: https://github.com/eth-cscs/DLA-Future
+[Nvidia]: https://www.nvidia.com/en-us/
+[PASC]: https://www.pasc-ch.org/
+[pika]: https://github.com/pika-org/pika
+[ScaLAPACK]: https://www.netlib.org/scalapack/

DOCUMENTATION.md

@@ -0,0 +1,30 @@
+# DLA-Future-Fortran Documentation
+
+## Documentation
+
+* [main](https://eth-cscs.github.io/DLA-Future-Fortran/main/)
+
+## How to generate the documentation
+
+The Fortran code is documented using [FORD] (FORtran Documenter), an automatic documentation generator for modern Fortran projects.
+
+```bash
+python -m ford --output_dir documentation DLA-Future-Fortran.md
+```
+
+## Documentation on GitHub
+
+The documentation is hosted on [GitHub Pages]. Documentation is generated automatically by the [GitHub Action] `.github/workflows/docs.yaml`
+for each version (`v*` tag) and for the `main` branch.
+
+The documentation is pushed by the [GitHub Action] to the `docs-ghpages` branch. This branch was manually created as an orphan branch with
+
+```bash
+git checkout --orphan docs-ghpages
+mkdir main && touch main/index.html
+git rm --cached -r . && git add main/index.html && git commit -m "empty docs" 
+git push --set-upstream origin docs-ghpages
+```
+
+[GitHub Pages]: https://pages.github.com
+[FORD]: https://forddocs.readthedocs.io/en/latest/

README.md

@@ -4,46 +4,9 @@
 
 Fortran interface for [DLA-Future], a task-based linear algebra library providing GPU-enabled distributed eigensolver.
 
-## Fortran API
+## Documentation
 
-The [DLA-Future] Fortran API provides the following functionality:
-
-* [DLA-Future] and [pika] initialization/finalization: `dlaf_initialize`/`dlaf_finalize`
-* Distributed grid creation/destruction: `dlaf_create_grid_from_blacs`/`dlaf_free_grid`
-* Cholesky decomposition: `dlaf_pXpotrf` (`X=s,d,c,z`)
-* Eigensolver for symmetric matrices: `dlaf_pXsyevd` (`X=s,d`)
-* Eigensolver for hermitian matrices: `dlaf_pXheevd` (`X=c,z`)
-* Generalised eigensolver for symmetric matrices: `dlaf_pXsygvx` (`X=s,d`)
-* Generalised eigensolver for hermitian matrices: `dlaf_pXhegvx` (`X=c,z`)
-
-## ScaLAPACK Drop-In
-
-The Fortran API (as well as the ScaLAPACK-like C API) is designed as drop-in replacement for ScaLAPACK.
-
-If you have a ScaLAPACK call in your code 
-```fortran
-call pzheevd(&
-    'V', 'L', n, &
-    a, 1, 1, desca, &
-    w, z, 1, 1, descz, &
-    work, lwork, rwork, lrwork, iwork, liwork, info &
-)
-```
-you can easily use DLA-Future as a drop-in replacement as follows (given a BLACS context `ictxt`):
-```fortran
-call dlaf_initialize()
-call dlaf_create_grid_from_blacs(ictxt)
-! ...
-call dlaf_pzheevd(&
-    'L', n, &
-    a, 1, 1, desca, &
-    w, z, 1, 1, descz, &
-    info &
-)
-! ...
-call dlaf_free_grid(ictxt)
-call dlaf_finalize()
-```
+[DLA-Future-Fortran Documentation](https://eth-cscs.github.io/DLA-Future-Fortran/main/).
 
 ## Citation