remake docs by lythx · Pull Request #40 · yaptide/for_developers

lythx · 2026-03-10T12:35:34Z

I created new docs, some pages are rewrites of the old docs, some are new. The base was generated by AI, I reviewed and fixed all the generated pages. There's a few TODOs which I'll resolve before merging.
I used Starlight instead of mkdocs, so the commands are different now:

npm run start - run and test locally
npm run build - build the production website
npm run preview - run the build

Github Pages workflow needs to be tested before merging.

grzanka · 2026-03-10T15:55:14Z

Can you update main README with instruction how to deploy locally ?

Copilot

Pull request overview

This PR migrates the YAPTIDE developer documentation site from a MkDocs/Poetry setup to an Astro + Starlight site, adds a new documentation content structure (architecture/backend/frontend/converter/API reference), and updates CI/dependabot to match the new Node-based build.

Changes:

Replace MkDocs configuration/content with an Astro + Starlight documentation site (new astro.config.mjs, package.json, content under src/content/docs/).
Add extensive new/updated developer documentation pages across setup, architecture, backend, frontend, converter, and API reference.
Update GitHub Pages workflow and Dependabot to use npm + Astro build output (dist/), and adjust repo-level config files (.gitignore, VSCode configs).

Reviewed changes

Copilot reviewed 73 out of 157 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`astro.config.mjs`	Starlight site configuration (site/base/sidebar/logo/edit link).
`package.json`	Introduces Astro/Starlight dependencies and build scripts.
`tsconfig.json`	Adds Astro strict TS config for the docs project.
`src/content.config.ts`	Configures Starlight docs collection loader/schema.
`src/styles/custom.css`	Custom theme tokens + landing-page card/badge styling.
`public/favicon.svg`	Adds SVG favicon with light/dark fill via media query.
`public/assets/logo.svg`	Adds static logo asset for the site.
`src/assets/yaptide-logo.svg`	Adds logo used by Starlight config.
`.gitignore`	Updates ignores for Astro (`dist/`, `.astro/`, `node_modules/`, env files).
`.vscode/launch.json`	Adds VSCode launch config for `astro dev`.
`.vscode/extensions.json`	Recommends Astro VSCode extension.
`.github/workflows/docs.yml`	Switches GitHub Pages build/deploy from MkDocs/Python to Astro/Node (`dist/`).
`.github/dependabot.yml`	Switches dependency updates from pip to npm (+ GitHub Actions).
`src/content/docs/index.mdx`	New developer docs landing page with mode matrix and navigation cards.
`src/content/docs/local-setup/local-frontend-demo.mdx`	Local “demo mode” (frontend-only) setup guide.
`src/content/docs/docker-setup/docker-frontend-demo.mdx`	Docker guide for serving demo build (currently includes TODO placeholders).
`src/content/docs/docker-setup/docker-celery.mdx`	Docker setup guide for backend + Celery workers (currently includes TODO placeholders).
`src/content/docs/docker-setup/docker-slurm.mdx`	Docker SLURM setup stub (currently TODO + tip block).
`src/content/docs/architecture/overview.md`	System-level architecture overview + diagram.
`src/content/docs/architecture/data-flow.md`	End-to-end data flow across direct/batch/local execution paths.
`src/content/docs/architecture/auth-model.md`	Auth model for native vs Keycloak + demo mode behavior.
`src/content/docs/backend/overview.md`	Backend architecture overview (Flask/Celery/Postgres).
`src/content/docs/backend/api-endpoints.md`	Narrative guide to backend endpoints and usage.
`src/content/docs/backend/database.md`	Database schema/model documentation and migration workflow.
`src/content/docs/backend/simulation-lifecycle.md`	Job/task state machine and direct vs batch execution details.
`src/content/docs/backend/simulator-management.md`	Simulator binary management via S3 + encryption.
`src/content/docs/backend/docker-deployment.md`	Docker Compose deployment guide for backend stack.
`src/content/docs/backend/testing.md`	Backend testing approach and fixtures.
`src/content/docs/frontend/overview.md`	Frontend architecture overview and directory structure.
`src/content/docs/frontend/3d-editor.md`	3D editor (Three.js) architecture and core patterns.
`src/content/docs/frontend/simulation-services.md`	Frontend simulation service abstraction and flows.
`src/content/docs/frontend/pyodide-converter.md`	In-browser converter via Pyodide + build pipeline.
`src/content/docs/frontend/geant4-wasm.md`	Geant4 WebAssembly runtime architecture and limitations.
`src/content/docs/frontend/auth-flows.md`	Standard vs Keycloak auth flows + demo mode behavior.
`src/content/docs/frontend/adding-commands.md`	Command-pattern guide for undo/redo and testing.
`src/content/docs/frontend/testing.md`	Frontend test strategy (Jest/RTL) + mocking patterns.
`src/content/docs/converter/overview.md`	Converter purpose, supported engines, and structure.
`src/content/docs/converter/conversion-flow.md`	End-to-end conversion pipeline explanation.
`src/content/docs/converter/adding-a-simulator.md`	How-to guide for adding a new converter engine.
`src/content/docs/converter/shieldhit.md`	SHIELD-HIT12A converter internals and formats.
`src/content/docs/converter/fluka.md`	FLUKA converter internals and card-based format.
`src/content/docs/converter/geant4.md`	Geant4 converter internals (GDML + macro).
`src/content/docs/converter/testing.md`	Converter testing strategy (golden files + unit tests).
`src/content/docs/contributing/guide.md`	Contribution workflow across repos.
`src/content/docs/contributing/code-style.md`	Style/lint conventions across Python/TS repos.
`src/content/docs/contributing/glossary.md`	Project glossary for domain and architecture terms.
`src/content/docs/api-reference/overview.md`	API reference overview + endpoint grouping.
`src/content/docs/api-reference/auth.md`	Auth endpoint reference.
`src/content/docs/api-reference/jobs.md`	Jobs endpoint reference.
`src/content/docs/api-reference/results.md`	Results/inputs/logs endpoint reference.
`src/content/docs/api-reference/user.md`	User/clusters endpoint reference.
`mkdocs.yml`	Removes MkDocs site config.
`pyproject.toml`	Removes Poetry/MkDocs dependency definition.
`docs/index.md`	Removes old MkDocs landing stub.
`docs/gen_ref_pages.py`	Removes MkDocs auto-reference generator script.
`docs/backend/*`	Removes old MkDocs backend docs.
`docs/frontend/*`	Removes old MkDocs frontend docs.
`docs/converter/*`	Removes old MkDocs converter docs.
`docs/documentation/index.md`	Removes old MkDocs “how docs work” page.

Comments suppressed due to low confidence (1)

.github/workflows/docs.yml:56

actions/configure-pages runs for pull_request events as well, but PRs (especially from forks) typically don't have GitHub Pages write permissions. Consider gating Pages-specific steps (configure-pages, upload-pages-artifact, deploy-pages) behind the same push && refs/heads/main condition, and keep PR runs to just npm ci/npm run build to avoid CI failures.

      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact if on main
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        uses: actions/upload-pages-artifact@v4
        with:
          path: 'dist'
      - name: Deploy to GitHub Pages if on main
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        id: deployment
        uses: actions/deploy-pages@v4

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-10T16:03:52Z

src/content/docs/docker-setup/docker-slurm.mdx

+:::tip
+  Prefer a local setup? See [Local — SLURM](/docs/local-setup/local-slurm/) for the non-containerized version.
+:::                                                          


The admonition block appears to be closed with ::: followed by trailing whitespace. Starlight/markdown-it container syntax typically expects the closing fence to be exactly :::; the extra spaces can prevent the tip block from closing/rendering correctly. Remove the trailing whitespace so the closing line is just :::.

Copilot · 2026-03-10T16:03:53Z

src/content/docs/index.mdx

+Welcome to the YAPTIDE developer documentation! Here you can find guides and resources for setting up a development environment, understanding the architecture, and contributing to the project. 
+The source code is hosted on [GitHub](https://github.com/yaptide/).
+
+To learn how to use the app, see the [user documentation](https://yaptide.github.io/docs/).
+


This link labels itself as "user documentation" but points to https://yaptide.github.io/docs/, which is also the configured base for this site (astro.config.mjs sets base: "/docs"). That makes the link circular/confusing. Point it to the actual user-facing docs location (or rename the link text if this site is intended to be the user docs).

Copilot · 2026-03-10T16:03:53Z

astro.config.mjs

+            }
+          ],
+        },
+          {


The sidebar config for the "Docker Setup" section has inconsistent indentation (the opening { is indented differently than the rest of the array items). While it still parses, it reads like an accidental nesting/copy-paste error and makes future edits risky. Reformat this block (e.g., run the repo formatter) so the sidebar array items are consistently aligned.

Suggested change

{

{

Copilot · 2026-03-10T16:03:53Z

src/content/docs/docker-setup/docker-frontend-demo.mdx

+## Prerequisites
+
+TODO Docker setup should not require Node.js or Python - change the dockerfile and update this guide
+
+- **Node.js 20+** with npm
+- **Python 3.9+** with pip and venv — needed to build the converter into a Pyodide/WebAssembly module (only if building locally)
+- **Docker**


There is a TODO placeholder in the published docs. If this page is meant to be user-facing, replace the TODO with actual prerequisites (or move it into an explicit "Known limitations" callout) so the guide is actionable.

Copilot · 2026-03-10T16:03:54Z

src/content/docs/docker-setup/docker-celery.mdx

+## Prerequisites
+
+TODO the Node.js and Python requirements should be removed for the docker setup - update the dockerfile and this guide
+
+- **Docker Engine 20.10+** with Docker Compose v2
+- **Node.js 20+** with npm (for the frontend, until the frontend Docker setup is complete)
+- **Python 3.9+** with pip and venv (for the converter submodule build, until the frontend Docker setup is complete)
+- **Git**


This page contains TODO placeholders (e.g., about removing Node.js/Python requirements and switching the frontend instructions to Docker). If this is intended for developers to follow today, please either complete these sections or clearly label them as not yet supported so readers don't follow partially correct instructions.

Copilot · 2026-03-10T16:03:54Z

src/content/docs/docker-setup/docker-celery.mdx

+## Step 3: Start the frontend
+
+TODO change this to use Docker instructions — the frontend currently requires a local setup
+
+The backend API is available at **http://localhost:5000** (via NGINX). Start the frontend in a separate terminal:
+```bash


This TODO indicates the core instructions are not yet Docker-based ("change this to use Docker instructions"). If the page is going into the sidebar/navigation, consider either completing this section or adding an explicit note that the Docker setup is currently backend-only and the frontend must be run locally, to avoid misleading readers.

remake docs

dfd526d

lythx had a problem deploying to github-pages March 10, 2026 12:35 — with GitHub Actions Failure

grzanka assigned lythx Mar 10, 2026

grzanka requested a review from Copilot March 10, 2026 15:53

Copilot started reviewing on behalf of grzanka March 10, 2026 15:54 View session

Copilot AI reviewed Mar 10, 2026

View reviewed changes

lythx added 4 commits March 10, 2026 19:04

move contributing up in the sidebar order and make it open by default

e355381

fix problems in setup docs

219f53c

remove unneeded sections and improve contributing docs

e252f13

remove json schema todo

a70d9ff

lythx had a problem deploying to github-pages March 10, 2026 18:05 — with GitHub Actions Failure

lythx added 7 commits March 10, 2026 19:12

fix astro config indent

40d7fdc

fix docker slurm guide whitespaces after :::

01fb65f

change base url from /docs to /for_developers

5a2cadb

fix base path and add favicon

9391216

add setup instructions in readme

cbfe2ba

add a 404 page to fix the gh actions fail

b9be01c

remove unneeded public folder

33a97b5

lythx had a problem deploying to github-pages March 10, 2026 18:34 — with GitHub Actions Failure

lythx added 2 commits March 10, 2026 19:45

change remaining TODOs to informational Work In Progress components

51a5335

fix GHA build error by disabling 404 page check

6afb6b9

lythx had a problem deploying to github-pages March 10, 2026 18:46 — with GitHub Actions Failure

fix GH Actions error by overriding zod version

5b0f0a8

lythx had a problem deploying to github-pages March 10, 2026 18:53 — with GitHub Actions Failure

fix GH Actions build fail by downgrading astrojs

8f81f71

lythx temporarily deployed to github-pages March 10, 2026 18:57 — with GitHub Actions Inactive

fix name and version in package.json

b94d41e

lythx temporarily deployed to github-pages March 10, 2026 18:59 — with GitHub Actions Inactive

change front docker instructions to use docker compose

385e060

lythx deployed to github-pages March 10, 2026 19:08 — with GitHub Actions Active

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

remake docs#40

remake docs#40
lythx wants to merge 18 commits intomainfrom
remake-docs

lythx commented Mar 10, 2026 •

edited

Loading

Uh oh!

grzanka commented Mar 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

lythx commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

grzanka commented Mar 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lythx commented Mar 10, 2026 •

edited

Loading