Merge pull request #16 from openscm/FORD_play

Added documentation of the Fortran back-end/API using [ford](https://forddocs.readthedocs.io/en/stable/).
Integrated the generated FORD docs into MkDocs so that the overall documentation is unified, searchable, and easy to navigate. The combined result looks solid.

Author: mzecc

.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/fortran-api/.gitkeep

@@ -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/gen_fortran_api.py

@@ -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).

docs/index.md

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

environment-docs-conda-base.yml

@@ -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!