feat: improve overall documentation experience - #282
Merged
Conversation
Contributor
Reviewer's GuideMigrates the documentation platform from Sphinx to a structured MkDocs Material site, reorganizes and substantially expands user-facing content, modernizes styling and media presentation, and updates dependency and GitHub Pages workflows for the new build output. Sequence diagram for documentation deploymentsequenceDiagram
participant GitHub as GitHub Actions
participant MkDocs
participant Site as site/
participant Pages as GitHub Pages
GitHub->>MkDocs: mkdocs build
MkDocs-->>Site: Generate static documentation
GitHub->>Site: cp CNAME site/
GitHub->>Pages: Deploy site/ with peaceiris/actions-gh-pages
Pages-->>GitHub: Published documentation site
Flow diagram for the new documentation structureflowchart TD
Home[Documentation home]
Intro[Introduction and setup]
Apps[Applications and Python library]
Hardware[Hardware and firmware]
Instruments[Instrument tutorials]
Contribution[Contribution guide]
Home --> Intro
Home --> Apps
Home --> Hardware
Home --> Instruments
Home --> Contribution
Intro --> WiFi[Wi-Fi setup]
Hardware --> Flashing[Firmware flashing]
File-Level Changes
Assessment against linked issues
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
rahul31124
marked this pull request as draft
August 29, 2026 10:25
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 4 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="docs/tutorials/accelerometer.md" line_range="11" />
<code_context>
+
+## Experiment: Measuring Acceleration
+
+{ align="right" width="200" }
+
+### Learning Objectives
</code_context>
<issue_to_address>
**issue (broader_impact):** The deployed MkDocs site contains no `images` directory, while the migrated pages reference dozens of files under `../images/`; all of those images render as broken links. The old deployment copied `images` into the generated site, but the new deployment only copies `CNAME`, and neither `docs/images` nor a root `images` directory exists.
**Suggested fix:** Move the image assets under `docs/images` or explicitly copy them into `site/images` during the build.
</issue_to_address>
### Comment 2
<location path="mkdocs.yml" line_range="8-9" />
<code_context>
+
+theme:
+ name: material
+ logo: assets/logo.png
+ favicon: assets/logo.png
+ font:
+ text: Roboto
</code_context>
<issue_to_address>
**issue (bug_risk):** MkDocs is configured to load `assets/logo.png` for both the logo and favicon, but that file does not exist in the repository, so the generated site has broken logo and favicon URLs.
**Suggested fix:** Add `docs/assets/logo.png` or point both settings at an existing asset.
</issue_to_address>
### Comment 3
<location path="docs/gettingstarted.md" line_range="25" />
<code_context>
- name: Build
run: |
</code_context>
<issue_to_address>
**issue:** The Getting Started page links to `wifi-guide.md`, but no such file exists under `docs`, so the Wi-Fi setup link leads to a 404 page.
**Triggers:** When a user follows the Wi-Fi setup link from Getting Started.
**Suggested fix:** Restore the Wi-Fi guide under `docs` or update the link to the correct existing page.
</issue_to_address>
### Comment 4
<location path="mkdocs.yml" line_range="64" />
<code_context>
+ - Robotic Arm: tutorials/roboticarm.md
+ - Gas Sensor: tutorials/gassensor.md
+ - Contribution:
+ - Collaborate: collaborate/Readme.md
</code_context>
<issue_to_address>
**issue (bug_risk):** The navigation declares `collaborate/Readme.md`, but that file is absent from the `docs` directory, so the Contribution navigation entry is broken or omitted during the MkDocs build.
**Triggers:** When the site is built or a user selects the Contribution section.
**Suggested fix:** Add `docs/collaborate/Readme.md` or remove/update the stale nav entry.
</issue_to_address>Sourcery assessment
Needs a human reviewer. 4 findings to address first, and the deployment workflow and build system are being replaced, so a broken MkDocs configuration or dependency could leave the published documentation site unavailable or deploy materially incorrect content; that outage or exposure occurs before a revert can help. Reverting and redeploying should restore the previous site, but it cannot undo the interval of failed or incorrect publication.
Blocking findings: docs/tutorials/accelerometer.md:11, mkdocs.yml:9, docs/gettingstarted.md:25, mkdocs.yml:64
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
pslab-documentation/docs/Readme.md
Line 38 in e8229c2
Replace the obsolete make-based build command
After this migration deletes the Makefile, conf.py, and Sphinx dependencies, the README still tells contributors to run make html; in a fresh checkout that target no longer exists, so local documentation builds fail before producing any output. Please update the build instructions to use the new MkDocs command.
Point contributors to the moved tutorial template
The migration moves the template to docs/tutorials/template.md and removes the root tutorials/ directory, but the collaboration guide still instructs experiment authors to follow tutorials/template.md; anyone following this guide from the repository root will not find the referenced file. Please update the path to the new location.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
rahul31124
marked this pull request as ready for review
August 30, 2026 16:10
Contributor
There was a problem hiding this comment.
Hey - I've found 2 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path=".github/workflows/deploy.yml" line_range="32" />
<code_context>
- cp -r images _build/html
- cp CNAME _build/html
- touch _build/html/.nojekyll
+ mkdocs build
+ cp CNAME site/
</code_context>
<issue_to_address>
**issue (broader_impact):** The deployed site contains broken images because MkDocs only copies files under `docs/`, while the new tutorial pages reference `../images/...` and no `docs/images` directory or referenced image files exists. The previous deployment explicitly copied the top-level `images` directory, but that handling was removed.
**Triggers:** When users open any tutorial containing an image.
**Suggested fix:** Move the image assets under `docs/images` or configure/copy them into the MkDocs output, and verify the referenced filenames exist.
</issue_to_address>
### Comment 2
<location path="mkdocs.yml" line_range="8-9" />
<code_context>
+
+theme:
+ name: material
+ logo: assets/logo.png
+ favicon: assets/logo.png
+ font:
+ text: Roboto
</code_context>
<issue_to_address>
**issue (bug_risk):** The Material theme is configured to load `assets/logo.png` for both the logo and favicon, but `docs/assets/logo.png` does not exist. The generated site therefore renders without the configured branding and favicon.
**Suggested fix:** Add `docs/assets/logo.png` or change both paths to an existing asset.
</issue_to_address>Sourcery assessment
Needs a human reviewer. 2 findings to address first, and the deployment workflow now depends on a new MkDocs toolchain and publishes a different output directory, while pull-request CI no longer builds the documentation; a configuration or asset-path mistake could leave GitHub Pages failing or serving broken content. Reverting restores the previous pipeline, but any deployment outage or incorrect site publication must still be corrected or redeployed.
Blocking findings: .github/workflows/deploy.yml:32, mkdocs.yml:9
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5c650ed81a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
marcnause
approved these changes
Aug 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #281
Description
This PR completely modernizes and improves the documentation site by migrating it from Sphinx to MkDocs and addressing several existing issues.
Changes Made
Video
pslab_doc.mp4
Result
The documentation site is now more modern, professional, responsive, and maintainable, with improved navigation, proper image rendering, better typography, and more complete documentation.
This PR aims to provide a significantly better documentation experience while preserving the existing content and improving areas that were previously incomplete or outdated.
Summary by Sourcery
Modernize the documentation platform and expand its content to provide a clearer, more complete, and responsive PSLab documentation experience.
New Features:
Bug Fixes:
Enhancements:
Build:
CI:
Documentation:
Chores:
Summary by Sourcery
Modernize and expand the PSLab documentation site with a structured, responsive MkDocs Material experience.
New Features:
Bug Fixes:
Enhancements:
Build:
CI:
Documentation:
Chores: