Add Fortran docs with FORD

.github/workflows/ci.yaml

@@ -39,6 +39,10 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           uv-dependency-install-flags: "--all-extras --group docs"
+      - name: Install Graphviz
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y graphviz
       - name: docs
         run: |
           uv run --no-sync mkdocs build --strict

.gitignore

@@ -17,6 +17,8 @@ docs/fgen/api/*
 !docs/fgen/api/.gitkeep
 docs/fgen-runtime/api/*
 !docs/fgen-runtime/api/.gitkeep
+docs/fortran-api/*
+!docs/fortran-api/.gitkeep
 
 # Databases
 *.db

changelog/16.docs.md

@@ -0,0 +1 @@
+Added documentation of the Fortran back-end/API using [ford](https://forddocs.readthedocs.io/en/stable/)

docs/NAVIGATION.md

@@ -13,4 +13,5 @@ See https://oprypin.github.io/mkdocs-literate-nav/
     - [Dependency pinning and testing](further-background/dependency-pinning-and-testing.md)
 - [Development](development.md)
 - [API reference](api/example_fgen_basic/)
+- [Fortran API](fortran-api/home.html)
 - [Changelog](changelog.md)

docs/development.md

@@ -31,6 +31,35 @@ Try and keep your merge requests as small as possible
 This makes life much easier for reviewers
 which allows contributions to be accepted at a faster rate.
 
+## Using uv with a compiled package
+
+Using uv with a compiled package is a bit more painful.
+Whenever you do `uv run` or `uv sync` or similar,
+uv tries to install the compiled package as an editable package.
+This can then cause issues on later calls to `uv run` or `uv sync`
+as having compiled packages as editable packages doesn't really work
+(you get errors like
+`ImportError: re-building the <package-name> meson-python editable wheel package failed`).
+The way around this is to:
+
+1. use the `--no-editable` flag with `uv sync`
+    so that uv doesn't do an editable install
+1. use the `--no-sync` flag with `uv run`
+    (and any other command that takes this flag)
+    so that `uv` doesn't try and re-build packages
+1. use the `--reinstall-package` flag with `uv run`
+    whenever you want to be sure that the latest changes
+    will be used for running a command
+    (yes, this makes running things slower,
+    but slower and reliable is better than broken)
+
+We include these flags in our `Makefile` and GitHub workflows
+if you want to see them in use.
+
+If you forget and run `uv run ...` in your terminal.
+The easiest solution seems to be to delete your virtual environment entirely and start again.
+We haven't found a way to get out of an accidental editable install.
+
 ## Language
 
 We use British English for our development.

docs/gen_fortran_api.py

@@ -0,0 +1,63 @@
+"""
+Drive Ford to create Fortran API docs
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import mkdocs_gen_files
+
+REPO_ROOT = Path(__file__).parents[1]
+
+FORD_OUTPUT_DIR = Path("docs") / "fortran-api"
+
+ford = shutil.which("ford")
+if ford is None:
+    msg = "Could not find FORD executable"
+    raise AssertionError(msg)
+
+subprocess.run(  # noqa: S603
+    [ford, "ford_config.md", "--output_dir", str(FORD_OUTPUT_DIR)],
+    check=True,
+)
+
+# Copy files across using mkdocs_gen_files
+# so it knows to include the files in the final docs.
+for entry in (REPO_ROOT / FORD_OUTPUT_DIR).rglob("*"):
+    if not entry.is_file():
+        continue
+
+    with open(entry, "rb") as fh:
+        contents = fh.read()
+
+    target_file = entry.relative_to(REPO_ROOT / "docs")
+    with mkdocs_gen_files.open(target_file, "wb") as fh:
+        fh.write(contents)
+
+    if target_file.name == "index.html":
+        # Also create a home.html file which we can point to from `NAVIGATION.md`.
+        # I don't know why just pointing to `index.html` doesn't work,
+        # but it doesn't (maybe cause `index.html` is a special name?).
+        target_file = target_file.parent / "home.html"
+
+        with mkdocs_gen_files.open(target_file, "wb") as fh:
+            fh.write(contents)
+
+# # If we want to move back to using literate-nav for maanging our navigation,
+# # also for the Fortran bits, we'll need something like the below
+# # and adjustments to the existing `NAVIGATION.md`.
+# with mkdocs_gen_files.open(
+#     (FORD_OUTPUT_DIR).relative_to("docs") / "NAVIGATION.md", "w"
+# ) as fh:
+#     fh.writelines("* [example_fgen_basic](home.html)")
+
+# Remove the ford files (which were just copied)
+shutil.rmtree(REPO_ROOT / FORD_OUTPUT_DIR)
+
+# Put back the gitkeep file
+gitkeep = REPO_ROOT / FORD_OUTPUT_DIR / ".gitkeep"
+gitkeep.parent.mkdir()
+gitkeep.touch()

docs/index.md

@@ -1 +1,10 @@
 ---8<--- "README.md:description"
+
+## API docs
+
+Our Python API is documented in [API][example_fgen_basic_1].
+The Fortran API is documented in [Fortran API](./fortran-api/).
+At present, the Fortran API docs are a sub-website so you can navigate to them
+but there are no buttons to navigate back to the main docs page
+(so you have to instead return yourself by re-entering the URL
+or pressing back, sorry, we hope to improve this in future).

environment-docs-conda-base.yml

@@ -9,3 +9,4 @@ dependencies:
   - pip
   - gcc
   - gfortran
+  - graphviz

ford_config.md

@@ -0,0 +1,8 @@
+---
+project: Example fgen - basic
+author: TODO align this with pyproject.toml
+src_dir: src
+graph: true
+---
+
+API docs for Fortran components!

mkdocs.yml

@@ -35,6 +35,7 @@ plugins:
   - gen-files:
       scripts:
         - docs/gen_doc_stubs.py
+        - docs/gen_fortran_api.py
   # Make the navigation easier to handle/auto-generate if we wish
   # https://oprypin.github.io/mkdocs-literate-nav/
   - literate-nav:
@@ -56,7 +57,7 @@ plugins:
       allow_errors: false
       # theme: dark
       include_source: True
-      ignore: ["*.ipynb", "*.md", "docs/gen_doc_stubs.py"]
+      ignore: ["*.ipynb", "*.md", "docs/gen_doc_stubs.py", "docs/gen_fortran_api.py"]
       remove_tag_config:
         remove_input_tags:
           - remove_input

pyproject.toml

@@ -77,6 +77,8 @@ docs = [
     # Key dependencies
     # ----------------
     "attrs>=25.3.0",
+    "ford>=6.0.1",
+    "graphviz>=0.21",
     "mkdocs-autorefs>=1.4.2",
     "mkdocs-gen-files>=0.5.0",
     "mkdocs-literate-nav>=0.6.2",

requirements-docs-locked.txt

@@ -29,8 +29,10 @@ exceptiongroup==1.3.0 ; python_full_version < '3.11'
 executing==2.1.0
 fastjsonschema==2.21.1
 fonttools==4.59.0
+ford==6.1.13
 fqdn==1.5.1
 ghp-import==2.1.0
+graphviz==0.21
 griffe==1.11.0
 h11==0.14.0
 httpcore==1.0.7
@@ -63,6 +65,7 @@ jupytext==1.17.2
 kiwisolver==1.4.7 ; python_full_version < '3.10'
 kiwisolver==1.4.9 ; python_full_version >= '3.10'
 markdown==3.7
+markdown-include==0.8.1
 markdown-it-py==3.0.0
 markupsafe==3.0.2
 matplotlib==3.9.4 ; python_full_version < '3.10'
@@ -112,6 +115,7 @@ pymdown-extensions==10.16.1
 pyparsing==3.2.3
 python-dateutil==2.9.0.post0
 python-json-logger==3.2.1
+python-markdown-math==0.9
 pywin32==308 ; platform_python_implementation != 'PyPy' and sys_platform == 'win32'
 pywinpty==2.0.14 ; os_name == 'nt'
 pyyaml==6.0.2
@@ -132,7 +136,9 @@ stack-data==0.6.3
 terminado==0.18.1
 tinycss2==1.4.0
 tomli==2.2.1 ; python_full_version < '3.11'
+toposort==1.10
 tornado==6.4.2
+tqdm==4.67.1
 traitlets==5.14.3
 types-python-dateutil==2.9.0.20241206
 typing-extensions==4.12.2