Add some project documentation

.github/workflows/cd-docs.yml

@@ -0,0 +1,43 @@
+name: Deploy Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - run: nix build '.#docs'
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./result/
+
+  deploy:
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -2,3 +2,10 @@
 __pycache__/
 *.py[cod]
 *$py.class
+
+# generated docs
+docs/index.md
+docs/reference/
+
+# docs site output/build directory
+site/

Makefile

@@ -24,6 +24,7 @@ check-static: ## Run static code checks
 check-static: fmt lint
 
 clean: ## Remove intermediate, cache, or build artifacts
+clean: clean-docs
 	find . -type f -name '*.py[cod]' -delete
 	find . -type d -name __pycache__ -print -exec rm -r {} +
 	find . -type d -name '*.egg-info' -print -exec rm -r {} +
@@ -32,12 +33,50 @@ clean: ## Remove intermediate, cache, or build artifacts
 	$(PY_RUN) ruff clean
 	-docker image rm $(PKG_NAME)
 
+clean-docs: ## Remove generated doc files
+	rm -f docs/index.md
+
+	rm -rf $(REFERENCE_DOC_DIR)
+	mkdir -p $(REFERENCE_DOC_DIR)
+	touch $(REFERENCE_DOC_DIR)/.keep
+
+	rm -rf site/
+
 clean-venv: ## Remove active virtualenv
 	rm -rf ./.venv/
 
 deps: ## Install dev dependencies
 	uv sync --dev
 
+.PHONY: docs
+docs: ## Generate documentation
+docs: docs/index.md docs-reference
+	$(PY_RUN) mkdocs build
+
+docs-watch: ## Start local server that will re-generate docs on file change
+docs-watch: docs-reference
+	$(PY_RUN) mkdocs serve
+
+docs/index.md: README.md
+	cp -f $< $@
+	sed -ri 's|\./docs/||g' $@
+
+REFERENCE_DOC_DIR := ./docs/reference
+
+python_module_files := $(shell find nava -type f -name '*.py')
+python_module_doc_files := $(patsubst %.py,$(REFERENCE_DOC_DIR)/%.md,$(python_module_files))
+
+docs-reference: $(python_module_doc_files)
+	find $(REFERENCE_DOC_DIR) -name '__init__.md' -print -exec bash -c 'mv $$0 $${0/__init__/index}' {} \;
+
+define python_module_name_from_file_name
+$(shell echo $(1) | sed 's/__init__.py//' | sed 's/.py//' | sed 's|/|\.|g' | sed 's/\.$$//')
+endef
+
+$(REFERENCE_DOC_DIR)/%.md: %.py
+	mkdir -p $(@D)
+	echo "::: $(call python_module_name_from_file_name, $<)" > $@
+
 fmt: ## Run formatter
 	$(PY_RUN) ruff format $(FMT_ARGS) $(PY_SRCS)
 

README.md

@@ -198,14 +198,15 @@ this)
 
 ## Getting Started
 
-After you have `nava-platform` installed, try
+After you have `nava-platform` installed, if you want to see the tool in action
+immediately, try:
 
 ```sh
 nava-platform infra install ./just-a-test
 ```
 
-to see it in action. Then read the docs for how to apply it to existing projects
-and more.
+Then read [the docs](./docs/getting-started/index.md) for how to apply it to
+existing projects and more.
 
 ### Shell Completion
 
@@ -281,3 +282,10 @@ The Makefile has a number of useful commands, see the output of `make help`.
 
 You may want to consider setting up a pre-commit hook for or just manually
 running `make check` before pushing work, as this will run useful checks.
+
+# Credits
+
+Icon designed by OpenMoji – the open-source emoji and icon project. License: [CC
+BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/#)
+
+Built on the back of [Copier](https://github.com/copier-org/copier).

docs/.pages

@@ -0,0 +1,4 @@
+nav:
+  - Overview: index.md
+  - getting-started
+  - ...

docs/adding-an-app.md

@@ -0,0 +1,32 @@
+# Adding an application
+
+## If using `template-infra`
+
+Whether you will use an existing application template or write your own, to add
+the infrastructure skeleton for hooking your application up, run:
+
+```sh
+nava-platform infra add-app . <APP_NAME>
+```
+
+## Using an application template
+
+If you want to use one of the `template-application-` from [the
+Platform](https://github.com/navapbc/platform/), run:
+
+```sh
+nava-platform app install --template-uri <TEMPLATE_URI> . <APP_NAME>
+```
+
+So for example, if you had a project utilizing the infrastructure template and
+wanted to add a new application based on the rails template, you would run:
+
+```sh
+nava-platform infra add-app --commit . my-super-awesome-app
+nava-platform app install --template-uri github:navapbc/template-application-rails --commit . my-super-awesome-app
+```
+
+The `app install` part may result in a conflict in the `<APP_NAME>/Makefile`
+file as the infrastructure template and the application template usually provide
+a different copy. Typically you'll want to just accept the application template
+version.

docs/avoiding-conflicts-on-update.md

@@ -0,0 +1,43 @@
+# Avoiding conflicts on update
+
+At the moment the "Nava Platform" is effectively just some structure around
+copying source files. This provides a lot of flexibility for projects to
+customize things to their needs, see exactly the code that changes between
+versions, and other benefits, but also introduces higher chances of merge
+conflicts on updating from upstream. There's logic in the Platform CLI to
+automatically resolve some of these, and thankfully Git can help tease things
+apart where we can't automatically resolve the conflicts, but you can also take
+steps to avoid some conflicts in the first place, as template maintainers and
+template users.
+
+> [!TIP]
+>
+> As is often the case, it is easier to resolve conflicts in smaller chucks.
+> Frequently updating from upstream can help avoid the worst situations.
+
+## Upstream in templates
+
+See [Template technical design
+principles](https://github.com/navapbc/template-infra/blob/main/template-only-docs/template-technical-design-principles.md)
+for general guidance.
+
+When possible, prefer to isolate template-owned files/configuration in separate
+files that can be imported into the proper runtime location. Provides users a
+way layer customization on top without having to edit files that might get
+touched on update.
+
+## Downstream template users
+
+### template-infra
+
+You may want to avoid creating `/infra/modules/` directories with very generic
+names. As upstream may eventually ship generic functionality (or a generic
+interface) for that use case, creating a situation where you may be blocked on
+updating until resolving all the conflicts. For example, for a non-upstream
+version of "notifications" for `<PROJECT_NAME>`, consider calling the module
+`<PROJECT_NAME>_notifications/` rather than `notifications/`.
+
+### Application templates
+
+No good advice at the moment. It can be hard to avoid conflicts given the nature
+of applications. But at least keep in mind which files are tracked upstream.

docs/getting-started/.pages

@@ -0,0 +1,4 @@
+nav:
+  - index.md
+  - migrating-from-legacy-template.md
+  - new-project.md

docs/getting-started/index.md

@@ -0,0 +1,6 @@
+# Getting Started
+
+For projects using the legacy install/update scripts, see [Migrating old
+templates to Nava Platform CLI](./migrating-from-legacy-template.md).
+
+For starting a new project, see [Starting a new project](./new-project.md)

docs/getting-started/migrating-from-legacy-template.md

@@ -0,0 +1,65 @@
+# Migrating old templates to Nava Platform CLI
+
+Previously templates would (generally) store the version installed into a
+`.<TEMPLATE_NAME>-version` file at the root of the project. Templates updated to
+use the Platform CLI track this info in a different way, so before utilizing the
+Platform CLI you'll need to convert the old file into the new format.
+
+The Platform CLI provides commands for doing this migration, though the exact
+steps you need to take will vary depending on what templates you have installed.
+
+> [!IMPORTANT]
+>
+> If you running a very old (pre-summer 2024) version of a template
+> (particularly `template-infra`), reach out to the platform team for some
+> guidance.
+
+## template-infra
+
+To transform the old `.template-version` file into the new format, run:
+
+```sh
+nava-platform infra migrate-from-legacy --commit .
+```
+
+This will result in a `.template-infra/` directory with a number of files inside
+of it. Check that the `app-<APP_NAME>.yml` files all coorespond to proper
+applications. Remove any that don't and update the commit.
+
+
+Now perform the update, with:
+
+```sh
+nava-platform infra update .
+```
+
+This will attempt to update the "base" template then each "app" instance in
+sequence. This will likely bail after updating the base infra template files,
+with a message to fix merge conflicts manually and run the update in parts. So
+fix the merge conflicts and commit.
+
+Then pickup the update from where it left off:
+
+```sh
+nava-platform infra update-app --all .
+```
+
+Likely you'll hit merge conflicts for each app as well, resolve those, commit,
+and move on to the next app, until you've done them all.
+
+## Application templates
+
+These are historically  less standard, so you'll have to provide a little more
+info, see `nava-platform app migrate-from-legacy --help`.
+
+```sh
+nava-platform app migrate-from-legacy --origin-template-uri <TEMPLATE_URI> --legacy-version-file <OLD_VERSION_FILE> . <APP_NAME>
+```
+
+The `<OLD_VERSION_FILE>` will likely be one of:
+
+- `.template-flask-version`
+- `.template-nextjs-version`
+- `.template-application-rails-version`
+
+but your project may have renamed it.

docs/getting-started/new-project.md

@@ -0,0 +1,23 @@
+# Starting a new project
+
+1. Create a project directory with `git init <MY_PROJECT_DIR>`
+1. `cd <MY_PROJECT_DIR>`
+1. Decide on what your first application is going to be called. We'll use
+   `<APP_NAME>` as the placeholder for what you choose in the following steps.
+1. Start with `template-infra` by running:
+    ```sh
+    nava-platform infra install --commit . <APP_NAME>
+    ```
+1. Then utilize one of the application templates for `<APP_NAME>` with:
+    ```sh
+    nava-platform app install --commit --template-uri <TEMPLATE_URI> . <APP_NAME>
+    ```
+1. Follow the steps in the `First time initialization` section of the generated
+   `/infra/README.md` file for creating the initial resources/dev environment.
+1. Once you have a dev environment created, enable a host of other features by running:
+    ```sh
+    nava-platform infra update --answers-only --data app_has_dev_env_setup=true .
+    ```
+
+And you're off!
+

docs/how-it-works.md

@@ -0,0 +1,11 @@
+# How it works
+
+The Platform CLI is largely a wrapper around
+[Copier](https://copier.readthedocs.io/en/stable/), with a few tweaks to support
+easier-to-reason-about file exclusions and answers files in the
+`.<TEMPLATE_NAME>/` subdirectories.
+
+Review [Copier's basic
+concepts](https://copier.readthedocs.io/en/stable/#basic-concepts) and [how
+updates
+work](https://copier.readthedocs.io/en/stable/updating/#how-the-update-works).

docs/stylesheets/extra.css

@@ -0,0 +1,12 @@
+.md-header__button.md-logo {
+  margin-top: 0;
+  margin-bottom: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+}
+
+.md-header__button.md-logo img,
+.md-header__button.md-logo svg {
+  height: 2.4rem;
+  width: 2.4rem;
+}