Docker (#121)

* Update dev environment

* Pixi toml update and settings

* Update miniforge path workflows

* Rounding due to numpy 2.0

* Add Dockerfile

* Update .gitignore

* Add cli to api.py

* Update pixi.toml

* Add custom inventory fetch (until fix in quartodoc)

* Moved old stuff to archive

* Update .gitignore

* Update pixi.toml

* Update pixi.toml

* Remove fiat env

* Add quarto for cli use

* Add description

* Add docker workflow

* Add run section to docker workflow

* Update docker workflow

* Update docker workflow

* Docker check mod

* chown

* sudo

* sudo

* ls

* docker test

* docker test

* docker test

* Working docker workflow

* Working docker workflow

* Added data gen task

* Updated docs with docker page; reorganized a little

* Updating the docs

* Adjusted docs workflow

* Api gen message

* Replace tmpdir w/ tmp_path

* Adjust test func name

* Stop support python 3.9

* Update changelog

.gitattributes

@@ -0,0 +1,6 @@
+*.yaml text eol=lf
+*.yml text eol=lf
+
+# GitHub syntax highlighting
+pixi.lock linguist-language=YAML# GitHub syntax highlighting
+pixi.lock linguist-language=YAML linguist-generated=true

.github/workflows/docker.yml

@@ -0,0 +1,46 @@
+---
+name: Docker testing
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  docs:
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest"]
+        include:
+          - os: ubuntu-latest
+            label: linux-64
+
+    name: ${{ matrix.label }}
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build docker image
+        run: |
+          docker build -f Dockerfile --build-arg="PIXIENV=default" --build-arg="UID=1001" -t fiat .
+
+      - name: Execute docker container
+        uses: addnab/docker-run-action@v3
+        with:
+          username: deltares
+          options: -v ${{ github.workspace }}/.testdata:/home/deltares/data
+          shell: bash
+          image: fiat:latest
+          run: |
+            pixi run python -m pip install tomli-w
+            pixi run python data/create_test_data.py
+            pixi run fiat run data/geom_event.toml
+            exit

.github/workflows/docs.yml

@@ -73,17 +73,16 @@ jobs:
         run: |
           sudo apt install -y expect
           cd docs
-          chmod u+x add_packages.sh
-          ./add_packages.sh
+          chmod u+x _scripts/add_packages.sh
+          _scripts/add_packages.sh
 
       - name: Setup api & testdata
         run: |
           export PATH=/home/runner/miniconda3/bin:$PATH
           mamba run -n fiat_docs python -m pip install tomli-w
           mamba run -n fiat_docs python .testdata/create_test_data.py
-          cd docs
-          mamba run -n fiat_docs python api.py
-          mamba run -n fiat_docs python -m quartodoc interlinks
+          mamba run -n fiat_docs python docs/_scripts/api.py docs/_quarto.yml
+          mamba run -n fiat_docs python docs/_scripts/inv.py interlinks docs/_quarto.yml
 
       - name: Generate docs
         run: |

.gitignore

@@ -24,6 +24,11 @@ __pycache__/
 tmp/
 whl/
 
+# pixi environments
+.pixi
+pixi.lock
+*.egg-info
+
 # C extensions
 *.so
 

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 ---
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.2.0
+    rev: v4.5.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -12,15 +12,11 @@ repos:
       - id: debug-statements
       - id: mixed-line-ending
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.270
+    rev: v0.1.2
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
-  - repo: https://github.com/psf/black
-    rev: 23.3.0
-    hooks:
-      - id: black
-        args: [--config=pyproject.toml]
+      - id: ruff-format
   # - repo: https://github.com/python-jsonschema/check-jsonschema
   #   rev: 0.24.0
   #   hooks:

Dockerfile

@@ -0,0 +1,28 @@
+FROM debian:bookworm-slim as base
+ARG PIXIENV
+ARG UID=1000
+RUN apt-get update && apt-get install -y curl
+
+RUN useradd deltares
+RUN usermod -u ${UID} deltares
+USER deltares
+WORKDIR /home/deltares
+
+RUN curl -fsSL https://pixi.sh/install.sh | bash
+ENV PATH=/home/deltares/.pixi/bin:$PATH
+COPY pixi.toml pyproject.toml README.md ./
+COPY --chown=deltares:deltares src/fiat ./src/fiat
+
+RUN chmod u+x src/ \
+  && pixi run -e ${PIXIENV} install-fiat \
+  && rm -rf .cache \
+  && find .pixi -type f -name "*.pyc" -delete
+
+# Workaround: write a file that runs pixi with correct environment.
+# This is needed because the argument is not passed to the entrypoint.
+ENV RUNENV="${PIXIENV}"
+RUN echo "pixi run --locked -e ${RUNENV} \$@" > run_pixi.sh \
+  && chown deltares:deltares run_pixi.sh \
+  && chmod u+x run_pixi.sh
+ENTRYPOINT ["sh", "run_pixi.sh"]
+CMD ["fiat","info"]

docs/_quarto.yml

@@ -48,8 +48,8 @@ website:
     search: true
     pinned: true
     left:
-      - text: Getting Started
-        file: getting_started/index.qmd
+      - text: Information
+        file: info/index.qmd
       - setup_guide/index.qmd
       - user_guide/index.qmd
       - api/index.qmd
@@ -67,22 +67,23 @@ website:
           - text: empty
 
   sidebar:
-    - title: "Getting started"
+    - title: "Information"
       border: true
       collapse-level: 3
       contents:
-        - text: Getting started
-          file: getting_started/index.qmd
+        - text: Information
+          file: info/index.qmd
         - text: Model information
           file: info/models.qmd
-        - getting_started/faq.qmd
+        - info/faq.qmd
     - title: "Setup guide"
       collapse-level: 3
       contents:
         - setup_guide/index.qmd
         - section: "General setup"
           contents:
             - "setup_guide/general/conda.qmd"
+            - "setup_guide/general/docker.qmd"
         - section: "FIAT package"
           contents:
             - setup_guide/kernel/installation.qmd

docs/api.py → docs/_scripts/api.py

@@ -1,5 +1,7 @@
 """Creating the API Reference for Delft-FIAT with the help of quartodoc."""
+import argparse
 import yaml
+import sys
 from pathlib import Path
 
 from quartodoc import (
@@ -9,6 +11,9 @@
 )
 from quartodoc.layout import DocAttribute, Page, Section
 
+from fiat.cli.util import file_path_check
+from fiat.cli.formatter import MainHelpFormatter
+
 
 def parse_content(
     cont: Page,
@@ -158,7 +163,7 @@ def create_tree(
         _description_
     """
     # set some meta info
-    p = Path(__file__).parent
+    p = Path(file).parent
 
     # Setup the builder and global blueprint
     b = Builder.from_quarto_config(file)
@@ -208,9 +213,50 @@ def create_tree(
     # Also write the index to the hard drive
     b.write_index(bp)
 
+    # Return the directory
+    return Path(p, rel_dir)
 
-if __name__ == "__main__":
-    p = Path(__file__).parent
-    yml = Path(p, "_quarto.yml").as_posix()
 
-    create_tree(yml)
+def run(args):
+    """Dummy run method."""
+    yml = file_path_check(args.config)
+    p = create_tree(yml.as_posix())
+    sys.stdout.write(f"Written api docs to {p.as_posix()}\n")
+
+
+def args_parser():
+    """A simple parser."""
+    parser = argparse.ArgumentParser(
+        #    usage="%(prog)s <options> <commands>",
+        add_help=False,
+        formatter_class=MainHelpFormatter,
+    )
+    # Simple help option
+    parser.add_argument(
+        "-h",
+        "--help",
+        action="help",
+        default=argparse.SUPPRESS,
+        help="Show this help message and exit",
+    )
+
+    # Add the quarto config file
+    parser.add_argument(
+        "config",
+        help="Path to the _quarto.yml settings file.",
+    )
+    # Set the default behaviour
+    parser.set_defaults(func=run)
+
+    # Return the parser
+    return parser
+
+
+def main(argv=sys.argv[1:]):
+    parser = args_parser()
+    args = parser.parse_args(args=None if argv else ["--help"])
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

docs/_scripts/inv.py

@@ -0,0 +1,74 @@
+import click
+import sphobjinv as soi
+import yaml
+from pathlib import Path
+from quartodoc import convert_inventory
+from quartodoc.interlinks import inventory_from_url
+
+
+@click.group()
+def cli():
+    pass
+
+
+@click.command(
+    short_help="Generate inventory files that the Quarto "
+    "`interlink` extension can use to auto-link to other docs."
+)
+@click.argument("config", default="_quarto.yml")
+@click.option("--dry-run", is_flag=True, default=False)
+@click.option("--fast", is_flag=True, default=False)
+def interlinks(config, dry_run, fast):
+    """
+    Generate inventory files that the Quarto `interlink` extension can use to
+    auto-link to other docs.
+
+    The files are stored in a cache directory, which defaults to _inv.
+    The Quarto extension `interlinks` will look for these files in the cache
+    and add links to your docs accordingly.
+    """
+
+    # config loading ----
+    cfg = yaml.safe_load(open(config))
+    interlinks = cfg.get("interlinks", {})
+
+    p_root = Path(config).parent
+
+    if not interlinks:
+        print("No interlinks field found in your quarto config. Quitting.")
+        return
+
+    # interlinks config settings ----
+    cache = p_root / "_inv"
+    cfg_fast = interlinks.get("fast", False)
+
+    fast = cfg_fast or fast
+
+    for k, v in interlinks["sources"].items():
+        # don't include user's own docs (users don't need to specify their own docs in
+        # the interlinks config anymore, so this is for backwards compat).
+        if v["url"] == "/":
+            continue
+
+        url = v["url"] + v.get("inv", "objects.inv")
+
+        inv = inventory_from_url(url)
+
+        p_dst = cache / f"{k}_objects"
+        p_dst.parent.mkdir(exist_ok=True, parents=True)
+
+        if fast:
+            # use sphobjinv to dump inv in txt format
+            df = inv.data_file()
+            soi.writebytes(p_dst.with_suffix(".txt"), df)
+
+        else:
+            # old behavior of converting to custom json format
+            convert_inventory(inv, p_dst.with_suffix(".json"))
+
+
+cli.add_command(interlinks)
+
+
+if __name__ == "__main__":
+    cli()