feat: Match deployment layout to URL-structure so the Fastify server can be replaced with a simple server; Simplify deployment docs.

docs/dev-guide/misc-deploying.md

@@ -1,37 +1,25 @@
 # Deploying this site
 
 A deployment of YScope docs includes both the current site and the sites of several other YScope
-repos and their release versions, complicating the build and deployment processes. The end goal is
-to use a single `node` process to serve each site at a different URL prefix (e.g., CLP at
-`/clp/main` and clp-ffi-py at `/clp-ffi-py/main`). We also want the layout on disk to be predictable
-so that we can use a simple config file to configure all the sites that need to be served.
+repos and their release versions, complicating the build and deployment processes. Ideally, we want:
 
-One approach would be to build all the sites using Task and then assemble them into a single
-deployment. However, since each site (and version) might have different build dependencies, we can't
-easily build them without several containers. Instead, we plan to have a GitHub workflow per repo
-which builds the site in a container and then publishes it directly to docs.yscope.com at the
-expected location.
+* to use a single webserver to serve each site at a different URL prefix (e.g., CLP at `/clp/main`
+  and clp-ffi-py at `/clp-ffi-py/main`).
+* the layout on disk to be predictable so that we can use a simple config file to configure all the
+  sites that need to be served.
 
-Until those workflows are ready, we will deploy by building all the sites individually and
-assembling them into a single deployment.
+Each site (one for each unique project and version of that project) may have different build
+dependencies, requiring unique building environments. This prevents us from building and assembling
+all the sites together using a single Task invocation. Instead, we build all sites individually
+before assembling them into a single deployment.
 
-## Deployment structure
+In the future, for each repo, we plan to have a GitHub workflow that builds the site in a container
+and then publishes it directly to docs.yscope.com at the expected location.
 
-An example of a deployment's structure on disk and the corresponding URL paths should is as follows:
+## Adding new projects
 
-| Project             | On-disk path                            | URL prefix         |
-|---------------------|-----------------------------------------|--------------------|
-| yscope-docs         | build/html                              | /                  |
-| clp @ main          | build/clp-main/build/docs/html          | /clp/main          |
-| clp-ffi-py @ main   | build/clp-ffi-py-main/build/docs/html   | /clp-ffi-py/main   |
-| clp-ffi-py @ v0.0.9 | build/clp-ffi-py-v0.0.9/build/docs/html | /clp-ffi-py/v0.0.9 |
-
-This assumes the deployment is in `build`. Essentially, for each project besides yscope-docs, the
-build output should be in `build/<project>-<version>/build/docs/html`.
-
-Each project and its versions should be listed in `conf/projects.json` so that the server knows all
-the sites it needs to render. The server will combine the config in `projects.json` with the build
-directory's path to generate routes similar to the previous table.
+Each project and its versions should be listed in `conf/projects.json` so that
+`scripts/download-projects.py` can download the repos and check out the correct versions.
 
 ## Step-by-step guide
 
@@ -50,11 +38,15 @@ directory's path to generate routes similar to the previous table.
 3. Build the docs for each project and version in `conf/projects.json`:
 
    ```shell
-   cd build/<project>-<version>
+   cd build/project-docs/<project>/<version>
    task docs:site
-   cd ../
    ```
 
+   :::{note}
+   Each project may have dependencies (e.g., a C++/Rust compiler) required to build the docs. See
+   the project's docs for details.
+   :::
+
 4. Assemble a release:
 
    ```shell
@@ -63,4 +55,4 @@ directory's path to generate routes similar to the previous table.
 
    The tar will be written to `build/yscope-docs-release.tar.gz`.
 5. Upload the tar to the deployment server and untar it.
-6. Follow the instructions in `yscope-docs-release/server/README.md` to start the server.
+6. Move the extracted content to wherever the webserver expects it to be.

scripts/download-projects.py

@@ -143,7 +143,7 @@ def main(argv):
         project: Project = Project.model_validate(project_dict, strict=True)
 
         for version in project.versions:
-            repo_dir = build_dir / f"{project.name}-{version}"
+            repo_dir = build_dir / project.name / version
             if repo_dir.exists():
                 if (
                         _dir_contains_repo(repo_dir, project.repo_url)