Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kirkrodrigues merged 8 commits into from
Mar 13, 2026
Merged

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

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
6d9fc3e
feat: Match deployment layout to URL-structure so the Fastify server …
kirkrodrigues Feb 28, 2026
1037f57
Fix order of task attributes.
kirkrodrigues Feb 28, 2026
3ce3ddc
Fix order of internal tasks.
kirkrodrigues Feb 28, 2026
fb0254d
Support serving even if no projects have been downloaded.
kirkrodrigues Feb 28, 2026
3efcfaf
Address 🐰 comments.
kirkrodrigues Feb 28, 2026
fe97bb6
Address 🐰 comments.
kirkrodrigues Feb 28, 2026
656a1ce
Address 🐰 comments.
kirkrodrigues Feb 28, 2026
bc38c92
Address Abby's review.
kirkrodrigues Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 7 additions & 20 deletions docs/dev-guide/misc-deploying.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

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.
to use a single webserve 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.

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
Expand All @@ -15,23 +15,10 @@ expected location.
Until those workflows are ready, we will deploy by building all the sites individually and
assembling them into a single deployment.

## Deployment structure
## Adding new projects

An example of a deployment's structure on disk and the corresponding URL paths should is as follows:

| 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.sh` can download the repos and check out the correct versions.

## Step-by-step guide

Expand Down Expand Up @@ -63,4 +50,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 webserve expects it to be.
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Feb 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Replace vague deploy target with a concrete path or config key.

“wherever the webserve expects it” is too ambiguous for deployment instructions. Please document the exact destination path (or the exact config field that defines it) to avoid operator drift.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/dev-guide/misc-deploying.md` at line 53, Replace the vague phrase in the
step "Move the extracted content to wherever the webserve expects it to be."
with an explicit destination: either a concrete filesystem path (e.g.,
/var/www/site or /usr/share/nginx/html) or the exact configuration key/name that
controls the webserver document root (e.g., nginx root in server block or the
webserve.config "document_root" field). Update the line to state the exact path
or config key and, if applicable, show the command or variable to verify that
destination so operators have an unambiguous deploy target.

2 changes: 1 addition & 1 deletion scripts/download-projects.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
7 changes: 0 additions & 7 deletions server/.env
View file
Open in desktop

This file was deleted.

1 change: 0 additions & 1 deletion server/.gitignore
View file
Open in desktop

This file was deleted.

33 changes: 0 additions & 33 deletions server/README.md
View file
Open in desktop

This file was deleted.

Loading