Improve Beluga landing page #301
Assignees
Labels
Comments
hidmic
added
documentation
hidmic
added a commit
that referenced
this issue
May 9, 2024
### Proposed changes This patch unifies all repository documentation in a common Sphinx site: high-level documentation lives in [MyST](https://mystmd.org/) flavor Markdown documents, Doxygen API documentation is pulled in using the `autodox` extension in https://github.com/Ekumen-OS/sphinx-babel. In the process, this PR partially addresses #301, #302, #303, #304, and #308. #### Type of change - [ ] 🐛 Bugfix (change which fixes an issue) - [ ] 🚀 Feature (change which adds functionality) - [x] 📚 Documentation (change which fixes or extends documentation) 💥 **Breaking change!** This patch changes the way we used to build documentation for the Beluga package. ### Checklist - [x] Lint and unit tests (if any) pass locally with my changes - [x] I have added tests that prove my fix is effective or that my feature works - [x] I have added necessary documentation (if appropriate) - [x] All commits have been signed for [DCO](https://developercertificate.org/) ### Additional comments This patch gets us 80% of the way towards release ready documentation. High-level documentation is not as polished as I would like to (specially the Key Concepts page), but this patch is big enough already and I'm too drained to produce quality technical writing. The easiest way to review this is building documentation locally and exploring it. You can check the README file under `docs` for instructions, or simply: ``` git clone https://github.com/Ekumen-OS/beluga.git cd beluga/docs python3 -m venv venv source venv/bin/activate pip install -r requirements.txt make html ``` Note this documentation needs Python 3.9 or later to build. I was not able to get all dependencies to play ball in earlier Python versions. --------- Signed-off-by: Michel Hidalgo <michel@ekumenlabs.com>
|
https://ekumen-os.github.io/beluga is much better than it used to be. It could still be better, and it will when the results of #163 go public. For the time being, I'll close this as done. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Feature description
Beluga's documentation landing page needs some work. A potential user should walk away with a clear understanding of why Beluga exists, what it offers, and why should they use it over the alternatives. Nav2's landing page is a good reference for this (https://navigation.ros.org).
Implementation considerations
Whichever tooling we decide to use for high-level documentation, it should be the same as that used for low-level documentation so that the whole user experience is consistent.
The text was updated successfully, but these errors were encountered: