Sphinx Documentation setup and refactoring#45
Open
NuwanJ wants to merge 1 commit into
Open
Conversation
There was a problem hiding this comment.
Pull request overview
This PR migrates the documentation site from a Jekyll/Ruby-based setup to a Sphinx + MyST Markdown build, with an updated build/deploy pipeline for GitHub Pages.
Changes:
- Replace Jekyll tooling (Gemfile/theme/layouts/includes/scripts) with a Sphinx project (
conf.py,index.rst) and uv-managed Python dependencies. - Update build/dev commands (
Makefile,README.md) and add a GitHub Pages workflow to build_sitevia Sphinx. - Refactor/restructure many docs pages into Sphinx toctrees (
*.rst) and MyST Markdown pages (*.md), including renames and content cleanup.
Reviewed changes
Copilot reviewed 122 out of 145 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/setup.sh | Removed Jekyll/Bundler setup script |
| scripts/run.sh | Removed Jekyll serve script |
| README.md | Updated contributor instructions for Sphinx/uv workflow |
| pyproject.toml | Added Python project metadata and Sphinx/MyST dependencies |
| minima.gemspec | Removed Jekyll theme gemspec |
| Makefile | Switched build/test/serve targets from Jekyll to Sphinx (uv) |
| index.rst | Added Sphinx root toctree and section entry points |
| Gemfile | Removed Ruby/Jekyll dependencies |
| docs/visualizer/index.rst | Added Sphinx index for Visualizer docs section |
| docs/visualizer/index.md | Removed old Jekyll page for Visualizer section |
| docs/visualizer/1_remote-access-guide.md | Removed old Jekyll remote access guide |
| docs/visualizer/02_local-setup-guide.md | Refactored Visualizer local setup guide for MyST/Sphinx |
| docs/visualizer/01_remote-access-guide.md | Added MyST remote access guide page |
| docs/sitemap.md | Removed Jekyll sitemap page front matter |
| docs/simulator/index.rst | Added Sphinx index for Simulator docs section |
| docs/simulator/01_mixed_reality_simulator.md | Refactored Simulator page for MyST/Sphinx and image linking |
| docs/robots/virtual/v1/java/4_robot-class.md | Removed old Jekyll Java robot class page |
| docs/robots/virtual/v1/index.md | Removed old Jekyll Virtual Robots index page |
| docs/robots/virtual/java/v1/index.rst | Added Sphinx index for Java virtual robots section |
| docs/robots/virtual/java/v1/05_swarm_class.md | Refactored Swarm/App class page for MyST/Sphinx |
| docs/robots/virtual/java/v1/04_robot_class.md | Added MyST Java robot class documentation page |
| docs/robots/virtual/java/v1/03_virtual_robot.md | Refactored virtual robot implementation guide and assets/links |
| docs/robots/virtual/java/v1/02_setup_guide_library.md | Refactored Java robot library setup guide for MyST/Sphinx |
| docs/robots/virtual/java/v1/01_setup_guide_robot.md | Refactored Java robot setup guide for MyST/Sphinx |
| docs/robots/virtual/java/v1/00_intro.md | Refactored Java virtual robot intro page metadata/content |
| docs/robots/obstacle/v1/index.md | Removed old Jekyll Obstacle Robots index page |
| docs/robots/obstacle/v1/hardware/index.rst | Added Sphinx index for Obstacle robot hardware section |
| docs/robots/obstacle/v1/hardware/3_pcb.md | Removed old Jekyll PCB page |
| docs/robots/obstacle/v1/hardware/2_schematics.md | Removed old Jekyll schematics page |
| docs/robots/obstacle/v1/hardware/1_intro.md | Removed old Jekyll hardware intro page |
| docs/robots/obstacle/v1/hardware/02_pcb.md | Added MyST PCB page with updated image linking |
| docs/robots/obstacle/v1/hardware/01_schematics.md | Added MyST schematics page with updated image linking |
| docs/robots/obstacle/v1/hardware/00_intro.md | Added MyST hardware intro page with updated image linking |
| docs/robots/obstacle/v1/hardware/0_index.md | Removed old Jekyll hardware index front matter page |
| docs/robots/obstacle/v1/firmware/index.rst | Added Sphinx index for Obstacle robot firmware section |
| docs/robots/obstacle/v1/firmware/02_setup_guide.md | Refactored firmware setup guide for MyST/Sphinx |
| docs/robots/obstacle/v1/firmware/01_intro.md | Refactored firmware intro/architecture page for MyST/Sphinx |
| docs/robots/obstacle/v1/firmware/00_overview.md | Refactored firmware overview page metadata/content |
| docs/robots/main/v4/index.md | Removed old Jekyll Main Robots index page |
| docs/robots/main/v4/hardware/index.rst | Added Sphinx index for Main robot hardware section |
| docs/robots/main/v4/hardware/4_diagrams.md | Removed old Jekyll diagrams page |
| docs/robots/main/v4/hardware/3_bom.md | Removed old Jekyll BOM page |
| docs/robots/main/v4/hardware/2_pcb.md | Removed old Jekyll PCB page |
| docs/robots/main/v4/hardware/1_schematics.md | Removed old Jekyll schematics page |
| docs/robots/main/v4/hardware/04_diagrams.md | Added MyST diagrams page with updated image linking |
| docs/robots/main/v4/hardware/03_bom.md | Added MyST BOM page with Markdown table |
| docs/robots/main/v4/hardware/02_pcb.md | Added MyST PCB page with updated image linking |
| docs/robots/main/v4/hardware/01_schematics.md | Added MyST schematics page with updated image linking |
| docs/robots/main/v4/hardware/00_intro.md | Added MyST hardware intro placeholder page |
| docs/robots/main/v4/hardware/0_intro.md | Removed old Jekyll hardware index front matter page |
| docs/robots/main/v4/firmware/index.rst | Added Sphinx index for Main robot firmware section |
| docs/robots/main/v4/firmware/15_neopixel.md | Refactored neopixel documentation formatting/links |
| docs/robots/main/v4/firmware/14_ir_sensors.md | Refactored IR sensor page structure and placeholder content |
| docs/robots/main/v4/firmware/13_compass.md | Refactored compass page structure and placeholder content |
| docs/robots/main/v4/firmware/12_colorSensor.md | Removed old Jekyll color sensor page |
| docs/robots/main/v4/firmware/12_color_sensor.md | Added MyST color sensor page placeholder |
| docs/robots/main/v4/firmware/11_distance_sensor.md | Refactored distance sensor documentation formatting/links |
| docs/robots/main/v4/firmware/10_motors.md | Refactored motors/encoders documentation formatting/links |
| docs/robots/main/v4/firmware/02_setup_guide.md | Refactored firmware setup guide for MyST/Sphinx |
| docs/robots/main/v4/firmware/01_intro.md | Refactored firmware architecture page and asset linking |
| docs/robots/main/v4/firmware/0_index.md | Removed old Jekyll firmware index page |
| docs/other/testing.md | Wrapped raw HTML in a MyST {raw} directive and adjusted metadata |
| docs/other/index.md | Removed old Jekyll “Other” index page |
| docs/other/documentation/index.rst | Added Sphinx index for documentation guide section |
| docs/other/documentation/1_page-template.md | Removed old Jekyll page template guide |
| docs/other/documentation/02_markdown.md | Refactored Markdown formats guide for MyST/Sphinx |
| docs/other/documentation/01_page-template.md | Added MyST page template guide |
| docs/other/documentation/0_index.md | Removed old Jekyll documentation index page |
| docs/localization/index.rst | Added Sphinx index for Localization docs section |
| docs/localization/index.md | Removed old Jekyll localization index page |
| docs/localization/02_calibration.md | Refactored calibration page for MyST/Sphinx and admonitions |
| docs/localization/01_setup.md | Refactored setup page for MyST/Sphinx and updated links |
| docs/home.md | Removed old Jekyll home page |
| docs/communication/mqtt/mqtt.md | Removed old Jekyll MQTT index page |
| docs/communication/mqtt/mqtt_sensor.md | Removed old Jekyll MQTT sensor protocols page |
| docs/communication/mqtt/mqtt_robot.md | Removed old Jekyll MQTT robot protocols page |
| docs/communication/mqtt/mqtt_obstacles.md | Removed old Jekyll MQTT obstacles protocols page |
| docs/communication/mqtt/mqtt_neopixel.md | Removed old Jekyll MQTT neopixel protocols page |
| docs/communication/mqtt/mqtt_localization.md | Removed old Jekyll MQTT localization protocols page |
| docs/communication/mqtt/mqtt_config.md | Removed old Jekyll MQTT config protocols page |
| docs/communication/mqtt/mqtt_communication.md | Removed old Jekyll MQTT communication protocols page |
| docs/communication/mqtt/index.rst | Added Sphinx index for MQTT protocols section |
| docs/communication/mqtt/07_config.md | Added MyST MQTT config protocols page |
| docs/communication/mqtt/06_neopixel.md | Added MyST MQTT neopixel protocols page |
| docs/communication/mqtt/05_sensor.md | Added MyST MQTT sensor protocols page |
| docs/communication/mqtt/04_obstacles.md | Added MyST MQTT obstacles protocols page |
| docs/communication/mqtt/03_communication.md | Added MyST MQTT communication protocols page |
| docs/communication/mqtt/02_localization.md | Added MyST MQTT localization protocols page |
| docs/communication/mqtt/01_robot.md | Added MyST MQTT robot protocols page |
| docs/communication/json/json.md | Removed old Jekyll JSON protocols index page |
| docs/communication/json/json_obstacles.md | Removed old Jekyll obstacles JSON schema page |
| docs/communication/json/index.rst | Added Sphinx index for JSON protocols section |
| docs/communication/json/02_environment.md | Refactored environment JSON page for MyST/Sphinx |
| docs/communication/json/01_obstacles.md | Added MyST obstacles JSON schema page |
| docs/communication/index.md | Removed old Jekyll Communication index page |
| docs/404.html | Removed Jekyll 404 page |
| conf.py | Added Sphinx configuration (MyST, theme, excludes, etc.) |
| assets/js/zzzz-search-data.json | Removed Jekyll-generated search data template |
| assets/js/vendor/lunr.min.js | Removed bundled Lunr dependency from old theme |
| assets/js/theme.js | Removed old theme JS |
| assets/css/index.css | Removed old theme CSS |
| .vscode/settings.json | Added editor defaults (Prettier/Ruff, formatting, interpreter path) |
| .python-version | Added pinned Python version for tooling/CI |
| .prettierrc.json | Added Prettier configuration |
| .prettierignore | Added Prettier ignore rules for build artifacts and Python files |
| .gitignore | Updated ignore list from Ruby/Jekyll to Python/Sphinx artifacts |
| .github/workflows/pages.yml | Added GitHub Pages workflow to build/deploy Sphinx site |
| _layouts/vendor/compress.html | Removed Jekyll HTML compression layout |
| _layouts/table_wrappers.html | Removed Jekyll table wrapper layout |
| _layouts/post.html | Removed Jekyll post layout |
| _layouts/page.html | Removed Jekyll page layout |
| _layouts/home.html | Removed Jekyll home layout |
| _layouts/default.html | Removed Jekyll default layout |
| _layouts/blank.html | Removed Jekyll blank layout |
| _layouts/about.html | Removed Jekyll about layout |
| _includes/thumbnail.html | Removed Jekyll include for thumbnail rendering |
| _includes/sidebar.html | Removed Jekyll sidebar/navigation include |
| _includes/pagination.html | Removed Jekyll pagination include |
| _includes/page_tree_builder.html | Removed Jekyll navigation tree builder include |
| _includes/head.html | Removed Jekyll head include and old asset wiring |
| _includes/google_analytics.html | Removed Jekyll Google Analytics include |
| _includes/footer_scripts.html | Removed Jekyll footer scripts include |
| _includes/breadcrumb.html | Removed Jekyll breadcrumb include |
| _includes/alert.html | Removed Jekyll alert include |
| _config.yml | Removed Jekyll site configuration |
Comments suppressed due to low confidence (5)
docs/robots/virtual/java/v1/03_virtual_robot.md:11
- This page links to
01_setup_guide.md, but the setup guide file in this folder is01_setup_guide_robot.md. Update the link target to the correct filename to avoid a broken intra-doc link.
docs/robots/virtual/java/v1/03_virtual_robot.md:120 - This reference points to
01_setup_guide.md, but the actual file is01_setup_guide_robot.mdin the same directory. Please update the link so it resolves correctly in the rendered docs.
docs/robots/virtual/java/v1/02_setup_guide_library.md:55 - This link points to
01_setup_guide.md, but the setup guide file in this directory is01_setup_guide_robot.md. Update the link target to avoid a broken relative link.
docs/localization/01_setup.md:61 - This link uses
2_calibration.md, but the calibration page in this section is02_calibration.md(as referenced by the toctree). Update the filename in the link so navigation works.
docs/robots/virtual/java/v1/05_swarm_class.md:74 - Typos in this paragraph/code comment reduce clarity (e.g.,
Insted→Instead, anduniquire→unique). Please fix these to keep the docs polished.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ## Writing Pages | ||
|
|
||
| Documentation articles live under `docs/`. Add new pages to the `index.md` toctree so they appear in the Sphinx navigation and are included in the build. |
Comment on lines
+18
to
+21
| Add pages to the root `index.rst` toctree so Sphinx includes them in the build and navigation. | ||
|
|
||
| Possible Markdown techniques can be found in [Markdown Techniques](2_markdown.md). | ||
|
|
Comment on lines
+13
to
+16
| | Destination | Server / GUI | | ||
| | Data Type | JSON | | ||
| | Message Format | `{"id": 10, "R": [R], "G": [B], "B": [B]}` | | ||
| | Description | Broadcast the RGB values of robot's NeoPixel LED ring to the Server/ GUI through the topic.<br><br>**id**: ID number of the robot<br>**R,G,B**: RGB color components | range: [0,255] | |
Comment on lines
+92
to
+96
| | Description | The sensor is entirely virtual and both virtual and physical robots can request the proximity readings from the simulator using this.<br><br>**angles**: relative angles that measures should be taken, as an integer list. Ex: `[-90, 0, 90]`<br>**reality(optional)**: V: virtual(default, and the only possible option far) | | ||
|
|
||
| ## Comapss Sensor | ||
|
|
||
| ### /sensor/compass/{robotID}/? |
Comment on lines
+12
to
+16
| - Microcontroller: Arduino Pro Mini (16 MHz, 3.3V) | ||
| - Power Source: 2 x Li-ion batteries | ||
| - Motiopn | ||
| - Motors: N20 Motors (180 rpm) | ||
| - Driver: L293D |
Comment on lines
+445
to
+451
| ##### getSlope(double x1, double y1, double x2, double y2) | ||
|
|
||
| Angle in degrees between two points. | ||
|
|
||
| ```java | ||
| motion.getSlop(idouble x1, double y1, double x2, double y2) | ||
| ``` |
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
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.
No description provided.