Merge branch 'main' into add-schema-generator

Author: toro-berlin

.github/pull_request_template.md

@@ -9,5 +9,5 @@
 ## Checklist
 
 - [ ] Tests pass: `uv run pytest`
-- [ ] Checks pass: `uv run pre-commit --all-files`
+- [ ] Checks pass: `uv run pre-commit run --all-files`
 - [ ] CHANGELOG is updated (if necessary)

.github/workflows/release.yaml

@@ -44,30 +44,3 @@ jobs:
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages-dir: ${{ needs.package_name.outputs.package_name}}/dist
-
-  docker:
-    name: Build Docker Image
-    runs-on: ubuntu-latest
-    needs: package_name
-    if: ${{ needs.package_name.outputs.package_name }} == 'stapi-fastapi'
-
-    permissions:
-      contents: read
-      packages: write
-      id-token: write
-
-    steps:
-      - name: Log in to the Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-      - name: Build and Push Docker Image
-        uses: docker/build-push-action@v6
-        with:
-          push: true
-          tags: stapi-spec/stapi-fastapi:${{ github.ref_name }}
-          build-args: PYTHON_VERSION='3.12'

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing
 
 First, thanks for contributing to **pystapi**!
-The [README](./README.md#development) as instructions on setting up your development environment, which is a great place to start.
+The [README](./README.md#development) has instructions on setting up your development environment, which is a great place to start.
 
 ## Repository organization
 

README.md

@@ -1,10 +1,54 @@
 # pystapi
 
 [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/stapi-spec/pystapi/ci.yaml?style=for-the-badge)](https://github.com/stapi-spec/pystapi/actions/workflows/ci.yaml)
+[![stapi-pydantic PyPI](https://img.shields.io/pypi/v/stapi-pydantic?style=for-the-badge&label=stapi-pydantic)](https://pypi.org/project/stapi-pydantic/)
+[![stapi-fastapi PyPI](https://img.shields.io/pypi/v/stapi-fastapi?style=for-the-badge&label=stapi-fastapi)](https://pypi.org/project/stapi-fastapi/)
 
 Monorepo for Python Satellite Tasking API (STAPI) Specification packages.
 For more, see our [docs](https://stapi-spec.github.io/pystapi/).
 
+> [!WARNING]
+> The STAPI spec, and these packages, are in their early stages of development.
+> There may be large shifts in the spec or these packages' APIs as we work towards a v1.0 release of the spec.
+
+## Packages
+
+There are several related packages in this monorepo:
+
+```mermaid
+graph
+    stapi-pydantic --> pystapi-client --> pystapi-validator
+    stapi-pydantic --> stapi-fastapi
+```
+
+### [stapi-pydantic](./stapi-pydantic/)
+
+[Pydantic](https://docs.pydantic.dev) models for STAPI.
+These models are used to generate the STAPI OpenAPI specification, and so can be considered the source-of-truth for STAPI data structures.
+
+### [stapi-fastapi](./stapi-fastapi/)
+
+A backend-agnostic [FastAPI](https://fastapi.tiangolo.com/) application for serving STAPI endpoints.
+A minimal test implementation is provided in [stapi-fastapi/tests/application.py](stapi-fastapi/tests/application.py).
+Run it like so:
+
+```commandline
+uv run fastapi dev stapi-fastapi/tests/application.py
+```
+
+The app should be accessible at `http://localhost:8000`.
+
+For implementations of **stapi-fastapi** with vendor-specific backends, see repos in the [stapi-fastapi Github organization](https://github.com/stapi-spec?q=stapi-fastapi-&type=all&language=&sort=).
+
+### [pystapi-client](./pystapi-client/)
+
+A Python API and command-line interface (CLI) for working with STAPI servers.
+
+### [pystapi-validator](./pystapi-validator/)
+
+A work-in-progress validator for STAPI APIs.
+Currently not very useful.
+
 ## Development
 
 Get [uv](https://docs.astral.sh/uv/), then:
@@ -24,7 +68,7 @@ uv run pytest
 Check formatting and other lints:
 
 ```shell
-uv run pre-commit --all-files
+uv run pre-commit run --all-files
 ```
 
 If you don't want to type `uv run` all the time:
@@ -34,28 +78,3 @@ source .venv/bin/activate
 ```
 
 See our [contribution guidelines](./CONTRIBUTING.md) for information on contributing any changes, fixes, or features.
-
-## Packages
-
-```mermaid
-graph
-    stapi-pydantic --> pystapi-client --> pystapi-validator
-    stapi-pydantic --> stapi-fastapi
-```
-
-### stapi-fastapi server
-
-A minimal test implementation is provided in [stapi-fastapi/tests/application.py](stapi-fastapi/tests/application.py).
-Run it like so:
-
-```commandline
-uv run fastapi dev stapi-fastapi/tests/application.py
-```
-
-The app should be accessible at `http://localhost:8000`.
-
-### stapi-client
-
-The `stapi-client` package is a Python client (CLI tool) focused on interfacing with the STAPI specification, specifically with a STAPI server. This is a work in progress.
-
-For more information, see the [README](pystapi-client/README.md).

RELEASING.md

@@ -3,14 +3,15 @@
 1. Determine which package you're releasing
 2. Determine the next version, following [semantic versioning](https://semver.org/)
 3. Create a release branch: `git checkout -b release/{package}-v{version}`
-4. Update that package's CHANGELOG with:
+4. Update that package's `pyproject.toml` with the new version
+5. Update that package's CHANGELOG with:
    - A new header with the new version
    - A new link at the bottom of the CHANGELOG for that header
-5. `git push -u origin`
-6. Once approved, merge the PR
-7. `git checkout main && git pull && scripts/release {package}`
-8. Go to the draft release href provided by the script, update that Github release with information from the CHANGELOG, and publish it
-9. Github actions will automatically publish a new PyPI release
+6. `git push -u origin`
+7. Once approved, merge the PR
+8. `git checkout main && git pull && scripts/release {package}`
+9. Go to the draft release href provided by the script, update that Github release with information from the CHANGELOG, and publish it
+10. Github actions will automatically publish a new PyPI release
 
 > [!IMPORTANT]
 > You'll need to set up [.netrc authentication](https://pygithub.readthedocs.io/en/stable/examples/Authentication.html#netrc-authentication) to use `scripts/release`.

docs/index.md

@@ -1 +1,8 @@
 # pystapi
+
+**pystapi** is the Python [monorepo](https://en.wikipedia.org/wiki/Monorepo) for the Satellite Tasking API (STAPI) specification.
+It contains three Python packages:
+
+- [stapi-pydantic](./stapi-pydantic.md): [Pydantic](https://docs.pydantic.dev) models that define the data structures in the STAPI specification
+- [stapi-fastapi](./stapi-fastapi.md): [FastAPI](https://fastapi.tiangolo.com/) routes and functions for building a STAPI server
+- [pystapi-client](./pystapi-client.md): a Python package and command-line interface (CLI) for interacting with a STAPI server

docs/pystapi-client.md

@@ -0,0 +1,7 @@
+# pystapi-client
+
+A Python client for working with [STAPI](https://stapi-spec.github.io/pystapi/) servers.
+
+## API
+
+::: pystapi_client

docs/pystapi-client/api.md

@@ -0,0 +1,7 @@
+# stapi-fastapi
+
+[FastAPI](https://fastapi.tiangolo.com/) routes and functions for building a STAPI server.
+
+## API
+
+::: stapi_fastapi