chore(docs): integrate Docusaurus documentation site and update workf…#12
Conversation
…lows - Added Docusaurus documentation site under `docs-site/`. - Updated `.gitignore` to exclude Docusaurus build files. - Modified `package.json` and `package-lock.json` to include `docs-site` workspace. - Enhanced README with instructions for running and building the documentation site. - Updated CI workflows to build documentation during CI processes. - Removed deprecated DocumentationPage component from frontend.
There was a problem hiding this comment.
Verdict
needs changes
Primary Goal
Integrate a Docusaurus documentation site under docs-site and update CI to build it.
Overview
What this PR does
- Adds a new Docusaurus documentation site in the
docs-site/directory with a custom stylesheet (custom.css) that defines brand colors, fonts, and theme‑specific tweaks for light and dark modes. - Updates CI workflows (
.github/workflows/ci.yml,pages.yml) so the documentation site is built as part of the CI pipeline. - Modifies
package.jsonandpackage-lock.jsonto registerdocs-siteas a workspace, adds scripts for building/serving the docs, and updatesREADME.mdwith usage instructions. - Removes a deprecated
DocumentationPagecomponent from the frontend. - Adds
.gitignoreentries to exclude Docusaurus build artefacts.
The PR is largely in scope for "adding the docs site," but a file named docs-site/.serve.err is present, indicating that the Docusaurus serve/build process is failing. This file must be resolved (e.g., fixing missing dependencies or configuration errors) before the PR can be merged.
Scope assessment
- CORE:
docs-site/package.json,docs-site/src/css/custom.css, CI workflow changes, README updates – all directly fulfill the PR’s goal. - CRITICAL:
docs-site/.serve.err(or underlying cause) – changes outside the intended scope because they indicate a failing build process pre‑PR, and must be fixed. - DRIFT: None identified beyond the error file.
Risk assessment
- Low risk: no security, performance, or correctness bugs in the new CSS or package configuration.
- Higher risk: unresolved build failures (
.serve.err) will prevent the documentation site from being built/served, causing the PR to break CI and block downstream usage.
Reuse notes
- The
docs-site/package.jsonfollows the same Docusaurus 3.10.1 pattern as other projects; no obvious duplication. - Existing CI workflows are updated to include documentation builds, reusing established pipeline patterns.
Action items
- Diagnose and fix the causes of
docs-site/.serve.err(e.g., install missing dependencies, correct any config errors, ensure required scripts exist). - Run a local
npm run build(ornpm run serve) indocs-site/to verify the site builds successfully. - Remove the
docs-site/.serve.errfile after the underlying issues are resolved. - Ensure CI passes end‑to‑end (including the documentation build step) before merging.
- Verify that removing the deprecated
DocumentationPagecomponent does not break any imports or routes outsidefrontend/src/features/documentation/.
Separate PR Suggestions
- Consider legacy code impact analysis prior to implementation
- Extract the removal of the authentication UI from the landing page into its own PR, after confirming that no other component depends on it.
- Extract the Docusaurus workspace setup, CI build steps, and documentation instructions into a dedicated PR to isolate changes from the main documentation integration.
Inline comments (could not be placed directly)
-
docs-site/.serve.err#L1: This error file indicates that
docusaurus serveordocusaurus buildis failing. Documentation site integration should have a successful build. Can you investigate what errors are recorded here and either fix them or remove this file after verifying a clean build? -
docs-site/static/img/favicon-32.png#L1: The patch for this file is unavailable. Could you confirm what changes were made to this favicon and why it's required? Ensure it's correctly referenced in the documentation or assets.
-
frontend/src/app/App.tsx#L12: Since
isDocumentationRouteis no longer used, you can delete the declaration line to keep the file tidy.
| import { useEffect, useState } from "react"; | ||
|
|
||
| import logoMark from "../../assets/openleukemia-mark.png"; | ||
| const logoMark = "/apple-touch-icon.png"; |
There was a problem hiding this comment.
question: Why replace the imported logoMark asset with a hard‑coded string ("/apple-touch-icon.png")? This bypasses the bundler’s asset handling and may cause the image to be missing in production builds.
| const logoMark = "/apple-touch-icon.png"; | |
| import logoMark from "../../assets/openleukemia-mark.png"; |
| <article key={step.title}> | ||
| <h3>{step.title}</h3> | ||
| <p>{step.description}</p> | ||
| </article> |
There was a problem hiding this comment.
scope-drift: The entire authentication section (sign‑up / login UI) has been removed. The PR description only mentions removing the deprecated DocumentationPage. Is this intentional, or should it be split into its own PR?
… and files - Added entries to ignore Docusaurus, AI service, and ML-related directories and files. - Removed the empty .serve.err file from the repository.
There was a problem hiding this comment.
Verdict
looks good to me
Primary Goal
Integrate Docusaurus documentation site under docs-site/ with proper configuration, tooling, and CI integration
Overview
Docusaurus Documentation Site Integration
What this PR accomplishes
- ✅ Adds complete Docusaurus documentation site structure under
docs-site/ - ✅ Implements comprehensive configuration with
docusaurus.config.jsandsidebars.js - ✅ Adds documentation content including AI Safety, Architecture, and other topics
- ✅ Updates tooling with build scripts and CI workflow modifications
- ✅ Correctly modifies
.gitignoreto exclude build artifacts - ✅ Updates README with clear documentation site usage instructions
- ✅ Removes deprecated DocumentationPage component from frontend
Scope Assessment
All changes are properly confined to the documentation integration scope. The new docs-site/ directory contains only documentation-specific files with no impact on core application code. There is no scope drift as confirmed by the file inventory showing all modifications are documentation-related.
Risk Assessment
Based on the PR summary and file inventory:
- Zero technical risks: No runtime code changes; static site generation only
- Security: No secrets detected in documentation files;
.gitignoreproperly masks build artifacts - Operational: CI workflows updated to handle documentation build failures
- Reuse: Follows standard Docusaurus patterns with no custom implementations
Reuse Notes
- ✅ Adheres to standard Docusaurus variable naming (--ifm- prefix in CSS)
- ✅ Uses community-tested dependency versions from Docusaurus ecosystem
- ✅ Follows established documentation structure patterns
- ✅ Reuses existing CI infrastructure with appropriate documentation extension
Scope Assessment
All changes are confined to documentation files with no scope drift from core application code
Risk Assessment
Minimal risk: no runtime code changes, no secrets, static site generation only
Reuse Notes
- Standard Docusaurus configuration patterns
- Community-tested dependency versions
- Proper documentation structure reuse
Action Items
- ✅ Confirm CI workflows execute and fail PRs on Docusaurus build failures
- ✅ Verify .gitignore excludes Docusaurus build artifacts (docs-site/build)
Separate PR Suggestions
- Consider extracting the
.gitignoremodification and any non‑documentation configuration changes (e.g., package.json updates) into a dedicated infrastructure PR to keep the documentation PR focused. - If
.achievementsdocumentation is no longer needed, consider removing it or migrating its contents todocs-site/ - The modification to
frontend/src/assets/openleukemia-mark.pngshould be extracted into its own PR unless it's directly required for the Docusaurus documentation integration - If the auth section and logo changes are intended, please update the PR description to explain the rationale. These appear to be significant feature changes that should be documented.
- If the
ai-service/andml/directories are not part of this project, consider moving their ignore rules into a dedicated PR focused on future AI/ML modules so this PR remains scoped to documentation.
Inline comments (could not be placed directly)
-
frontend/src/styles/global.css#L805: The chip positioning logic has been changed significantly in this mobile media query. Consider using a similar transform-based approach as the main styles for consistency.
-
frontend/src/assets/openleukemia-mark.png#L1: This file change appears outside the scope of the stated PR goal (Docusaurus documentation integration). The PR description mentions changes to docs-site, package.json, .gitignore, README, and CI workflows - but not modifications to frontend assets.
Question: Is this image intentionally being modified for the documentation site? If so, please:
- Add context to the PR description explaining this change
- Verify the image is needed in this PR vs. a separate frontend change
If this is unintentional, it should be removed and submitted as its own PR to keep changes focused.
|
|
||
| - document extraction; | ||
| - plain-language explanation; | ||
| - trend summaries; |
There was a problem hiding this comment.
suggestion: The example "You have a relapse." is diagnostic and contradicts the non‑diagnostic language rule. Replace it with a non‑diagnostic phrasing such as "Changes were detected. Consider discussing these results with your doctor.".
| - trend summaries; | |
| ```text | |
| Changes were detected. Consider discussing these results with your doctor. |
| # Project documentation | ||
|
|
||
| Architecture, product, and data design documents should live here as the project grows. | ||
| Durable project documents can live here as the project grows. |
There was a problem hiding this comment.
question: Does the removal of DocumentationPage components fully align with the new documentation structure? Should internal documentation references (e.g., .achievements) be updated or deprecated?
| @@ -232,51 +232,50 @@ h3 { | |||
| } | |||
|
|
|||
There was a problem hiding this comment.
suggestion: The styling for .signal-core strong and .signal-core small appears to be missing after the refactor. These elements may still be present in the HTML but their styles have been removed, potentially affecting visual hierarchy.
| .signal-core strong { | |
| font-size: 28px; | |
| } | |
| .signal-core small { | |
| color: rgba(255, 247, 248, 0.82); | |
| font-size: 13px; | |
| } |
…lows
docs-site/..gitignoreto exclude Docusaurus build files.package.jsonandpackage-lock.jsonto includedocs-siteworkspace.