developmentseed / developmentseed/titiler-covjson

Publish a documentation site with ProperDocs and move user-facing guidance out of README

Open
#63 0 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Python
Stars
1
Forks
1
Avg merge
2d 1h
Merged PRs (30d)
12

Description

## Context

User-facing operational guidance is starting to accrete in `README.md`. The first instance is the dataset error-status override added in #37 (how a trusted deployment remaps `RasterioIOError` to a `4xx`), and more deployment, configuration, and per-endpoint usage guidance will follow as the endpoint surface grows. README is the right home for an overview and a quick start, but not for a growing body of deployment and operations documentation.

The repository also has no documentation framework. The numbered files in `docs/` (design overview, API definition, data model reference, and so on) are design-history references and ADRs, not a rendered, navigable, published site aimed at users and deployers; today a reader browses raw Markdown on GitHub.

This issue is to stand up a published documentation site and migrate user-facing guidance into it, so README stays lean and deployment/usage docs get a proper home.

## Proposal: ProperDocs

Adopt [ProperDocs](https://properdocs.org/) as the documentation site generator. It fits this repo well:

- Markdown source with a single `properdocs.yml` config; `docs_dir` defaults to `docs/`, so the existing Markdown files slot in without relocation.
- A built-in dev server (`properdocs serve`) with auto-reload, plus full-text search.
- A static-site build (`properdocs build` produces `site/`) deployable to GitHub Pages or any static host.
- Extensible via themes, plugins, and Python-Markdown extensions; per-release versioning is available via `mike` if we want it later.

Setup sketch (since `docs/` already exists, we add `properdocs.yml` by hand rather than scaffold a fresh project with `properdocs new`):

```bash
pip install properdocs properdocs-theme-mkdocs
properdocs serve # preview at http://127.0.0.1:8000/
properdocs build # produces site/ (add to .gitignore)
```

```yaml
# properdocs.yml (sketch; theme is an open question below)
site_name: titiler-covjson
docs_dir: docs
theme: mkdocs
nav:
- Home: index.md
- Guides:
- Deployment and error handling: guides/deployment.md
- Reference:
- /bbox endpoint: 08-bbox-endpoint-spec.md
- Architecture decisions: adr/README.md
- Design history (superseded): ...
```

## Scope

- Add ProperDocs and a theme as a `docs` dependency group; add `properdocs.yml`; gitignore `site/`.
- Define the `nav` so current, user-facing material (endpoint reference, a deployment/error-handling guide, ADRs) is separated from the superseded early-design docs, so the site never presents stale sketches as current.
- Create a Deployment (or Usage) guide page and **move the #37 error-status override section into it**, leaving README with a short pointer. Fold the existing `add_exception_handlers` install guidance in too, so the handler story lives in one place.
- Trim README to overview, install, a minimal quick start, and a link to the published docs site.
- Add a CI job to build the site and publish to GitHub Pages on push to `main`.

## Out of scope

- Rewriting the design-history documents (they keep their superseded notes).
- `mike` per-version documentation (revisit once there are releases to version).

## Open questions

- Theme: the bundled `mkdocs`/`readthedocs` theme, or something else?
- Publish to GitHub Pages, or another host?
- How to present the superseded design docs in the nav: a clearly-labeled "Design history" section, or drop them from the site and keep them repo-only?

## Related

- #37 (dataset open/read error-status override): its README section is the first content to migrate.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing README.md, the existing docs/ files, and the #37 guidance to identify current user-facing material and superseded design references. Define the ProperDocs configuration and navigation, move the error-status and add_exception_handlers guidance into a deployment or usage page, and add the requested build-and-publish CI job. Done means the site builds, README points to it, stale material is clearly separated, and pushes to main publish it.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, python
Domain
ci-cd, documentation, release
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.