Merge pull request #128 from BritishGeologicalSurvey/docs

init ghpages

.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

docs/bgs_rules.md

@@ -0,0 +1 @@
+::: app.bgs_rules

docs/checkers.md

@@ -0,0 +1 @@
+::: app.checkers

docs/conversion.md

@@ -0,0 +1 @@
+::: app.conversion

docs/errors.md

@@ -0,0 +1 @@
+::: app.errors

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

docs/main.md

@@ -0,0 +1 @@
+::: app.main

docs/routes.md

@@ -0,0 +1 @@
+::: app.routes

docs/validation.md

@@ -0,0 +1 @@
+::: app.validation

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