Skip to content
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

Jump to bottom

Build documentation using Sphinx #441

Merged
merged 59 commits into from
Jul 11, 2024
Merged

Build documentation using Sphinx #441

merged 59 commits into from
Jul 11, 2024

Conversation

azeey
Copy link
Contributor

@azeey azeey commented May 15, 2024 •
edited
Loading

🎉 New feature

Partially resolves #412

Summary

Uses sphinx to build the documentation contained in this repository. While the goal is to migrate all of gazebosim.org to a static site, for now, we'll have the landing page, the "features" and "showcase" pages be served by https://github.com/gazebo-web/gazebosim-web-frontend as is currently and the /docs endpoint be directed to the output of sphinx. This is similar to how the /api endpoint is directed to the output of doxygen.

Since sphinx has its own of organizing files and structuring the table of contents, a custom script (build_multiversion.py) is needed to take our existing metadata files (index.yaml) and make the necessary changes to the markdown files. For this, it is necessary to copy the files to a temporary directory. The script also handles differences in URL endpoints and markdown files, which must match in Sphinx. Lastly, for version switching and searching to work properly, each version of Gazebo is built independently by the build_multiversion.py script.

Inspired by https://github.com/ros2/ros2_documentation

Needs pydata/pydata-sphinx-theme#1795 for the version switcher to work properly.

Screenshots

Light theme:
image

Dark theme:
image

Test it

Follow updated README to build the docs

Preview

cc @nuclearsandwich

TODO:

  • Handle latest and all links
  • Add "Edit this page" link
  • Handle warnings related to external links (e.g. /libs/math). Maybe create /libs via sphinx.
  • Handle ionic so it shows up as (dev)
  • Add GitHub workflow to build and deploy automatically
  • Deploy doxygen generated content to GitHub pages.

Checklist

  • Signed all commits for DCO
  • Added tests
  • Added example and/or tutorial
  • Updated documentation (as needed)
  • Updated migration guide (as needed)
  • Consider updating Python bindings (if the library has them)
  • codecheck passed (See contributing)
  • All tests passed (See test coverage)
  • While waiting for a review on your PR, please help review another open pull request to support the maintainers

Note to maintainers: Remember to use Squash-Merge and edit the commit message to match the pull request summary while retaining Signed-off-by messages.

azeey added 2 commits May 15, 2024 16:47
@azeey
Build documentation using Sphinx
7946324 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Build documentation using Sphinx
a6afd14 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@github-actions github-actions bot added 🎵 harmonic Gazebo Harmonic 🔮 dome Ignition Dome labels May 15, 2024
@azeey azeey added documentation Improvements or additions to documentation and removed 🔮 dome Ignition Dome 🎵 harmonic Gazebo Harmonic labels May 15, 2024
azeey and others added 23 commits May 21, 2024 17:40
@azeey
Add documentation for Gazebo vendor packages
5f30f92 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Indicate that Gazebo Fortress is recommended for ROS 2 Humble and Iro…
e3049d5 
…n users (#437)

Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@j-rivero @ahcorde @azeey
Installing Gazebo11 side by side with new Gazebo Tutorial (#438)
10742d5 
* Installing Gazebo11 side by side with new Gazebo Tutorial
---------

Signed-off-by: Jose Luis Rivero <jrivero@osrfoundation.org>
Co-authored-by: Alejandro Hernández Cordero <ahcorde@gmail.com>
@j-rivero @azeey
Minor updates on Noble references (#439)
9795585 
Signed-off-by: Jose Luis Rivero <jrivero@osrfoundation.org>
@scpeters @azeey
contributing.md: suggest multi-repo features target main (#440)
4d2759b 
Signed-off-by: Steve Peters <scpeters@openrobotics.org>
@azeey
Build documentation using Sphinx
51b6f90 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Enable 'edit this page'
9ab84fc 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Suppress warnings for external links
99fd22c 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Update warning style
28c3b54 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Handle dev and old versions, fix going to the correct page after vers…
dc03207 
…ion selection

Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Use different background for eol vs supported versions
650a3e4 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Add .gitignore
c9ab794 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Add /libs
7653220 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Refactor
7582ec7 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Fetch content from github
289cacb 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Add individual library pages
65fcaf6 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Add support for "latest" and "all"
ba16cad 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Merge remote-tracking branch 'origin/master' into gz_vendor_pkgs
66b4cf1 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Check if symlink already exists
44a1f69 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Fix formatting of /libs pagse
bf0f3ce 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Add redirect from /docs
99eb778 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Share conf.py file between docs and libs
d5f3024 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Add option for building pointers
f0e8e85 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
azeey added 7 commits July 1, 2024 21:02
@azeey
Update permissions
eff9088 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Test on test_sphinx_docs
c9c68bb 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Parallel builds
268ea01 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Fix upload
4366b60 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Fix yaml
ec8d140 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Add concurrency
cd5e151 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Merge branch 'test_sphinx_docs' into azeey/sphinx_docs
14684e5 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@github-actions github-actions bot added 🌱 garden Gazebo Garden 🎵 harmonic Gazebo Harmonic 🏢 edifice Ignition Edifice 🏯 fortress Ignition Fortress 🏰 citadel Ignition Citadel 📜 blueprint Ignition Blueprint 🔮 dome Ignition Dome labels Jul 2, 2024
@azeey
Remove test_sphinx_docs
e44c638 
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
@azeey
Copy link
Contributor Author

azeey commented Jul 2, 2024

@nuclearsandwich this is now ready for you to look at.

@azeey azeey merged commit 710a025 into master Jul 11, 2024
5 checks passed
@azeey azeey deleted the azeey/sphinx_docs branch July 11, 2024 00:53
This was referenced Jul 17, 2024
Merged
Closed
Closed
Closed
Closed
Closed
This was referenced Jul 26, 2024
Closed
Merged
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@nuclearsandwich nuclearsandwich nuclearsandwich approved these changes

@iche033 iche033 iche033 approved these changes

@mabelzhang mabelzhang Awaiting requested review from mabelzhang mabelzhang is a code owner

Assignees
No one assigned
Labels
📜 blueprint Ignition Blueprint 🏰 citadel Ignition Citadel documentation Improvements or additions to documentation 🔮 dome Ignition Dome 🏢 edifice Ignition Edifice 🏯 fortress Ignition Fortress 🌱 garden Gazebo Garden 🎵 harmonic Gazebo Harmonic
Projects
Core development
Archived in project
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Use a static site generator for gazebosim.org
5 participants
@azeey @nuclearsandwich @iche033 @j-rivero @scpeters