Merge pull request #16 from ricardogsilva/3-add-docs

Add documentation website

Author: ricardogsilva

docs/development.md

@@ -0,0 +1,90 @@
+---
+hide:
+   - navigation
+---
+
+# Development
+
+cite-runner is implemented in Python.
+
+The standalone application depends on the following third-party projects:
+
+- [typer] for CLI commands
+- [pydantic] for models
+- [jinja] for output format templates
+- [httpx] for making network requests
+- [lxml] for parsing teamengine responses
+- [mkdocs] for documentation
+
+### Brief implementation overview
+
+cite-runner runs CITE tests suites by calling [teamengine's web API]. It
+requests test suite results in the EARL (AKA the W3C Evaluation and Report
+Language) format, which is XML-based.
+
+After obtaining a test suite run result in EARL format, cite-runner parses it
+into an instance of `models.TestSuiteResult`, its internal data structure.From
+there, it is able to serialize it into either JSON or markdown.
+
+
+### Setting up a develoment environment
+
+In a brief nutshell:
+
+1. Fork the cite-runner repository
+
+2. Clone you fork to your local environment
+
+3. Install [poetry]
+
+4. Use poetry to install the cite-runner code locally, also including the
+   `dev` dependency group (and optionally also the `docs` group, if you plan
+   to work on docs):
+
+    ```shell
+    poetry install --with dev --with docs
+    ```
+
+5. Optionally (but strongly recommended) enable the [pre-commit] hooks
+   provided by cite-runner:
+
+    ```shell
+    poetry run pre-commit install
+    ```
+
+6. Stand up a docker container with a local teamengine instance:
+
+    ```shell
+    docker run \
+        --rm \
+        --name=teamengine \
+        --network=host \
+        ogccite/teamengine-production:1.0-SNAPSHOT
+    ```
+
+    You should now be able to use `http:localhost:8080/teamengine` in
+    cite-runner
+
+    !!! warning
+
+        teamengine will try to run on your local port `8080`, which could
+        potentially already be occupied by another application.
+
+7. Work on the cite-runner code
+
+8. If you want to work on documentation, you can start the mkdocs server with:
+
+    ```shell
+    poetry run mkdocs serve
+    ```
+
+
+[httpx]: https://www.python-httpx.org/
+[jinja]: https://jinja.palletsprojects.com/en/stable/
+[lxml]: https://lxml.de/
+[mkdocs]: https://www.mkdocs.org/
+[poetry]: https://python-poetry.org/
+[pre-commit]: https://pre-commit.com/
+[pydantic]: https://docs.pydantic.dev/latest/
+[teamengine's web API]: https://opengeospatial.github.io/teamengine/users.html
+[typer]: https://typer.tiangolo.com/

docs/index.md

@@ -0,0 +1,59 @@
+---
+hide:
+  - navigation
+---
+
+# CITE Runner
+
+A test runner for [OGC CITE].
+
+Key features:
+
+- **Runs as a github action**: Can be integrated into existing CI workflows
+- **Runs as a standalone CLI application**: Can be run as a standalone tool
+- **Multiple output formats**: Can output test suite results as markdown,
+  JSON or XML
+
+This project aims to simplify the running of OGC CITE tests suites so that
+server implementations of OGC standards may ensure their compliance with them
+more frequently.
+
+[OGC CITE]: https://github.com/opengeospatial/cite/wiki
+
+
+## Examples
+
+Integrate into your CI as a github action:
+
+```yaml
+jobs:
+  perform-cite-testing:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: test ogcapi-features compliancy
+        uses: OSGEO/cite-runner@main
+        with:
+          test_suite_identifier: ogcapi-features-1.0
+          test_session_arguments: >-
+            iut=http://localhost:5001
+            noofcollections=-1
+```
+
+Run the same test suite as a standalone CLI application:
+
+```shell
+cite-runner execute-test-suite \
+    http://localhost:8080/teamengine \
+    ogcapi-features-1.0 \
+    --test-suite-input iut http://localhost:5001 \
+    --test-suite-input noofcollections -1 \
+    --output-format markdown
+```
+
+
+## License
+
+cite-runner is published under an [MIT license].
+
+
+[MIT license]: https://github.com/OSGeo/cite-runner/blob/main/LICENSE

docs/ogc-test-suites.md

@@ -0,0 +1,59 @@
+---
+hide:
+  - navigation
+---
+
+# Test suites which are known to work
+
+<table>
+<thead>
+<tr>
+<th>test suite identifier</th>
+<th>arguments</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+    <td>ogcapi-features-1.0</td>
+    <td>
+      <ul>
+        <li>iut</li>
+        <li>noofcollections</li>
+      </ul>
+    </td>
+</tr>
+<tr>
+    <td>ogcapi-processes-1.0</td>
+    <td>
+      <ul>
+        <li>iut</li>
+        <li>noofcollections</li>
+      </ul>
+    </td>
+</tr>
+<tr>
+    <td>ogcapi-edr10</td>
+    <td>
+      <ul>
+        <li>iut</li>
+        <li>apiDefinition</li>
+      </ul>
+    </td>
+</tr>
+<tr>
+    <td>ogcapi-tiles10</td>
+    <td>
+      <ul>
+        <li>iut</li>
+        <li>tilematrixsetdefnitionuri</li>
+        <li>urltemplatefortiles</li>
+        <li>tilematrix</li>
+        <li>mintilerow</li>
+        <li>maxtilerow</li>
+        <li>mintilecol</li>
+        <li>maxtilecol</li>
+      </ul>
+    </td>
+</tr>
+</tbody>
+</table>