diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 00000000..2c651d18 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,29 @@ +name: pages +on: + push: + branches: + - main +permissions: + contents: write +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Configure Git Credentials + run: | + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + - uses: actions/setup-python@v4 + with: + python-version: 3.x + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + - uses: actions/cache@v3 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + - run: pip install mkdocs-material + - run: pip install 'mkdocstrings[python]' + - run: mkdocs gh-deploy --force \ No newline at end of file diff --git a/docs/bgs_rules.md b/docs/bgs_rules.md new file mode 100644 index 00000000..479bf28d --- /dev/null +++ b/docs/bgs_rules.md @@ -0,0 +1 @@ +::: app.bgs_rules diff --git a/docs/checkers.md b/docs/checkers.md new file mode 100644 index 00000000..ba6919cd --- /dev/null +++ b/docs/checkers.md @@ -0,0 +1 @@ +::: app.checkers diff --git a/docs/conversion.md b/docs/conversion.md new file mode 100644 index 00000000..102defb0 --- /dev/null +++ b/docs/conversion.md @@ -0,0 +1 @@ +::: app.conversion diff --git a/docs/errors.md b/docs/errors.md new file mode 100644 index 00000000..22664239 --- /dev/null +++ b/docs/errors.md @@ -0,0 +1 @@ +::: app.errors diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..a30a4977 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,112 @@ +# Welcome to pyagsapi - AGS File Utilities API + +A HTTP API for the [AGS Python library](https://gitlab.com/ags-data-format-wg/ags-python-library). + +It can: + +- Validate AGS files to v4.x of the AGS data format standard +- Validate AGS files for submission to the [National Geoscience Data Center (NGDC)](http://transfer.bgs.ac.uk/ingestion) +- Convert between AGS format files and spreadsheet files `.ags` <-> `.xlsx` +- Download PDF logs of existing files within the National Geoscience Data Centre + +It is built on the FastAPI framework, using the official FastAPI Docker image. + +The core Python API provides the functionality to validate and convert AGS geotechnical data. From here, standard Python web frameworks like Uvicorn and Starlette provide the web API/wrapper atop the core Python API. + +## Quick start + +### Docker + +The simplest way to run the validation service is via Docker: + +``` +docker run -p 80:80 --name pyagsapi ghcr.io/britishgeologicalsurvey/pyagsapi:latest +``` + +Navigate to [http://localhost](http://localhost) to see the landing page or [http://localhost/docs](http://localhost/docs) to see the API documentation via the Swagger interface. + +The `latest` tag reflects the current state of the `main` branch of the repository. It may have breaking changes. Use versions from tagged [Releases](https://github.com/BritishGeologicalSurvey/pyagsapi/releases) to fix the version in deployment pipelines. Available tags are listed in the [Container Registry](https://github.com/BritishGeologicalSurvey/AGS-Validator/pkgs/container/pyagsapi). + +### Setting the `root_path` + +If you are running behind a proxy, you may need to set the `root_path` using the `PYAGSAPI_ROOT_PATH` environment variable: + +``` +docker run -p 80:80 -e PYAGSAPI_ROOT_PATH="/pyagsapi" --name pyagsapi ghcr.io/britishgeologicalsurvey/pyagsapi +``` + +This will ensure that all references to `self` in responses, and all Swagger and REDOC documentation, include the correct path. + +### From Source + +pyagsapi runs on Python >= 3.11. + +```bash +python -m venv pyagsapi +source pyagsapi/bin/activate +git clone https://github.com/BritishGeologicalSurvey/pyagsapi.git +cd pyagsapi +pip install -r requirements.txt +uvicorn app.main:app +``` + +## Development + +The main repo for this project is [https://github.com/BritishGeologicalSurvey/pyagsapi/](https://github.com/BritishGeologicalSurvey/pyagsapi/). + +Please raise any feature requests, issues or pull requests against this repository. + +### Running locally + +AGS Validator is written in Python and based on the [FastAPI](https://fastapi.tiangolo.com/) framework. It runs on the [Uvicorn](https://www.uvicorn.org/) ASGI server. + +Use the instructions above to run the API locally. + +By default, the API is served at [http://localhost:8000](http://localhost:8000). + +### Running tests + +Use the following to run the tests: + +```bash +pip install -r requirements_dev.txt +export PYTHONPATH=. +pytest -vs test +``` + +The test environment is configured so that adding `--pdb` to the test command will start an IPython debugger session in the event of test failure. + +### GUI Customisation + +To ammend the GUI HTML we recommend running via `Docker` using your own `Dockerfile` like the below to `COPY` in your own templates. + +``` +FROM ghcr.io/britishgeologicalsurvey/pyagsapi:2.0 + +COPY content/static /app/app/static +COPY content/templates /app/app/templates +``` + +## Container Registry + +Containers for the application are hosted in the GitHub Container Registry + +Every push to `Main` branch commits builds `pyagsapi:latest`. + +Push Tagged Releases with `^v?[0-9]+[.][0-9]+([.][0-9])?` (v* == v2.0) builds `pyagsapi:2.0` (the "v" gets dropped for the tag). + +You can also push release candidates using the format `/^v?[0-9]+[.][0-9]+([.][0-9])?\-rc/` e.g. v3.1.1-rc builds `pyagsapi:3.1.1-rc` + +## Example Files + +Files in [https://github.com/BritishGeologicalSurvey/pyagsapi/tree/main/test/files/real](https://github.com/BritishGeologicalSurvey/pyagsapi/tree/main/test/files/real) are a random collection of real AGS files which have been submitted to the BGS and are available under OGL, we have included them here as example files for testing pyagsapi. + +## Licence + +`pyagsapi` was created by and is maintained by the British Geological Survey. +It is distributed under the [LGPL v3.0 licence](https://spdx.org/licenses/LGPL-3.0-or-later.html). +Copyright: © BGS / UKRI 2021 + +Contains data supplied by Natural Environment Research Council. + +Contains public sector information licensed under the Open Government Licence v3.0 diff --git a/docs/main.md b/docs/main.md new file mode 100644 index 00000000..2209f424 --- /dev/null +++ b/docs/main.md @@ -0,0 +1 @@ +::: app.main \ No newline at end of file diff --git a/docs/routes.md b/docs/routes.md new file mode 100644 index 00000000..3dd39536 --- /dev/null +++ b/docs/routes.md @@ -0,0 +1 @@ +::: app.routes diff --git a/docs/validation.md b/docs/validation.md new file mode 100644 index 00000000..55e6021d --- /dev/null +++ b/docs/validation.md @@ -0,0 +1 @@ +::: app.validation diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..4c0a9568 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,50 @@ +site_name: Official documentation - pyagsapi +repo_url: https://github.com/BritishGeologicalSurvey/pyagsapi + +theme: + name: "material" + palette: + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: teal + accent: purple + toggle: + icon: material/weather-sunny + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + accent: lime + toggle: + icon: material/weather-night + name: Switch to system preference + features: + - navigation.expand + - content.code.copy + +plugins: +- search: +- mkdocstrings: + handlers: + python: + paths: [] + options: + docstring_style: numpy + members_order: source + filters: ["!^_"] + docstring_section_style: table + +nav: + - Introduction: index.md + - Code: + - main.py: main.md + - validation.py: validation.md + - bgs_rules.py: bgs_rules.md + - routes.py: routes.md + - conversion.py: conversion.md + - checkers.py: checkers.md + - errors.py: errors.md