azeey commented 4 months ago

🎉 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 https://github.com/pydata/pydata-sphinx-theme/pull/1795 for the version switcher to work properly.

Screenshots

Light theme:

Dark theme:

Test it

Follow updated README to build the docs

Preview

cc @nuclearsandwich

TODO:

[x] Handle latest and all links
[x] Add "Edit this page" link
[x] Handle warnings related to external links (e.g. /libs/math). Maybe create /libs via sphinx.
[x] Handle ionic so it shows up as (dev)
[x] 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 commented 3 months ago

Preview: https://addisu.taddese.com/docs/ deployed by https://github.com/azeey/docs/actions/workflows/deploy.yml. It has both the frontend and the docs.