Skip to content

Conversation

@dgarcia360
Copy link
Contributor

@dgarcia360 dgarcia360 commented Feb 21, 2025

Deletes Doxygen docs and adds Sphinx & the BlueRobotics theme to this project:

image

For more information, see Python docs generation.

How to test

  1. Clone this PR.
  2. Go to the docs folder: cd docs.
  3. Run make preview.
  4. Open http://127.0.0.1:5500/ and preview the site.

@dgarcia360
Copy link
Contributor Author

@patrickelectric Ready for review. After merging, docs will be published at https://docs.bluerobotics.com/ping-python

@patrickelectric
Copy link
Member

Hi @dgarcia360, it would be nice to have the CI running without deployment to validate PR and avoid break of the build system.
Another thing, is it normal to have the code block lines separated ?

image

@dgarcia360 dgarcia360 marked this pull request as draft March 11, 2025 01:02
@dgarcia360
Copy link
Contributor Author

@patrickelectric Moving to "Draft" while I add a workflow that runs on every PR to ensure the build doesn’t break.

Another thing, is it normal to have the code block lines separated ?

That’s the autodoc2 extension’s default behavior, but I’ll check if we can override it.

@dgarcia360 dgarcia360 marked this pull request as ready for review March 13, 2025 17:35
@dgarcia360
Copy link
Contributor Author

Marking as ready for review just to debug the GitHub Actions error, do not merge yet

fix: pingmessage.py warning

chore: optimization

chore: fix action

rm: directory flag
@dgarcia360 dgarcia360 marked this pull request as draft March 13, 2025 18:57
@dgarcia360
Copy link
Contributor Author

Reviewing the code block lines separated issue and docstrings not rendering

@dgarcia360
Copy link
Contributor Author

@patrickelectric Added the PR verification workflow and investigated autodoc2 styling.

Functions were rendering one per line because they were not displaying the function descriptions underneath:

image

This happened because the Python generator expected comments in the Google style docstring format, bu, but they were written using Doxygen syntax instead.

Google Style docstring:

image

Doxygen:

image

To resolve this, we switched the generator from autodoc to breathe + exhale, which supports Doxygen. Now, descriptions are rendering correctly:

image

@dgarcia360 dgarcia360 marked this pull request as ready for review March 14, 2025 08:00
@patrickelectric patrickelectric merged commit 8205da9 into bluerobotics:master Mar 24, 2025
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants