Add breathe and doxylink for doxygen integration by sipke · Pull Request #45 · OpenAMP/openamp-docs

sipke · 2025-03-24T05:27:16Z

In order to be able to embed and link to doxygen content generated by submodules libmetal and openamp, add the sphinx extensions breathe and doxylink.

Adding these, though not trivial, will enable better consolidation of documentation between doxygen of submodule and openamp-docs docs.

Requires pull request changes in libmetal and openamp for the embedding/linking to actually work, otherwise it will give error in build output, though will not block rest of document build.
OpenAMP/libmetal#329
OpenAMP/open-amp#641

openamp-docs git submodule for open-amp and libmetal have been bumped to make the change effective for these repository document generation.

arnopo · 2025-03-25T15:51:34Z

@sipke
could you create a temporary commit that update the openamp submode to point to your open-amp and libmetal github? That would allow to see the generated doc.

sipke · 2025-03-26T09:58:15Z

Added the requested temporary commit as well as content changes to demonstrate how breathe and doxylink work.

Not sure why the readthedocs build did not succeed on checkout, the commit should be there.

Alternate locations of examples:
See https://sipke-openamp-docs.readthedocs.io/en/sv-develop/docs/data_structures.html
and
https://sipke-openamp-docs.readthedocs.io/en/sv-develop/docs/porting_guide.html
which has examples of each.

edmooring

Looks OK to me.,

sipke · 2025-05-19T04:53:27Z

Updated this pull request with new temporary submodule commits for open-amp and libmetal as well as updated remoteproc_design and rpmsg_design with embedded doxygen using breathe extension. I think this should cover the review request items

point to API page generated by doxygen, instead of duplicating the API

for issue 38.
If the libmetal and open-amp pull requests are merged and the submodules in this openamp-docs repository updated, I can rebase this to allow for merging.
OpenAMP/libmetal#329
OpenAMP/open-amp#641

sipke · 2025-05-26T03:40:24Z

Bumped open-amp and libmetal git modules to those with xml and tag file generated by doxygen so this could now be merged as they are not longer temporary commits.
Just noticed that main already auto-updates the gitmodules, so probably main-next needs to be force updated first, after which this branch probably needs rebasing...

arnopo · 2025-05-26T14:33:18Z

you should be able to rebase it now, I mergered main branch in main-next to align the documentation

arnopo · 2025-06-10T09:34:07Z

+.. doxygenstruct:: vring
+   :members:
+
+Refer also :openamp_doc_link:`vring <vring>` documentation and `vring code implementation <https://github.com/OpenAMP/open-amp/blob/main/lib/include/openamp/virtio_ring.h>`_.


seems that there is an issue here on doc generation:
https://openamp--45.org.readthedocs.build/en/45/docs/data_structures_content.html#_CPPv45vring

That looks to be in doxygen generated content (included via breathe), so might be in code comments. Will have to check.

to address in a separate PR, I created the issue #63

arnopo · 2025-06-10T09:50:05Z

 Platform Specific Remoteproc Driver
 ***********************************

+<<<<<<< HEAD


merge conflict need to be fixed in this commit

I did some rebase mistake there I'll need to check. Had fixed it so must have pushed wrong branch or similar.

Secondary commit had fixed the forgotten merge conflict, but first hadn't. Squashed the commits into one, as both were adding breathe/doxylink, as b72a3b4

arnopo · 2025-06-10T09:50:20Z

 Platform Specific Porting to Use Remoteproc to Manage Remote Processor
 **********************************************************************

+<<<<<<< HEAD


arnopo · 2025-06-10T10:11:13Z

@@ -0,0 +1,136 @@
+Remoteproc Design Document


your proposal is not crystal clear to me. Here, you duplicate the documentation. Do you propose to remove the file in open-amp repo?
What about changing the format from markdown to RST directly in open-amp repo?

I had read mention of you possibly wanting to move documentation to openamp-docs and only doxygen in code repos, or something like that, so I did this to show how breathe and doxylink looks without needing to change code repos. It's up to you which you prefer to do, then I can change code repos from md to rst or delete md file in code repos and move images from code repos to openamp-docs too.

I just tested changing md to rst in open-amp repo, and adjusting references in openamp-docs repo, and that works the same, so if you can let me know which of the two locations you want by next week, I can adjust and then create PRs in open-amp repo to either

change md to rst or

delete docs and images

@arnopo / @wmamills if you could let me know if you prefer these design docs to move to openamp-docs repository, or stay in open-amp.
If they stay in open-amp repo, then I suspect they would not generate in that repository cleanly, as the changes require breathe and doxylink, until a similar readthedocs build flow would be created in open-amp repo as is in openamp-docs.

meeting done to discuss the design base on breathe:
decision:

integrate this PR and move forward with breathe

move md and image documentation from openamp repository to openamp-doc repository and convert file in RST.

arnopo

this PR need also to be rebase to solve conflicts

arnopo · 2025-06-18T16:24:31Z


-If you want to contribute and port OpenAMP to your platform read more about OpenAMP porting
-:ref:`here<porting-guide-work-label>`.
+You are encouraged to contribute to the OpenAMP project to help create a successful solution through a vibrant and engaged community.


Please apply the rule done on .rst files on the main branch: 100 chars max per line as much as possible

arnopo · 2025-06-18T16:29:13Z

  {
-	/* Instantiate the remoteproc instance */
-	remoteproc_init(&rproc, &rproc_ops, &private_data);
+    /* Instantiate the remoteproc instance */


tabulation is part of the formating coding ruleof the libraries , I would prefer to keep them except if that generates issues

put back, but still needs two spaces for the formatting at start. using a tab (instead of two spaces at start) does not format as well.

Add breathe extension to requirements.txt to allow embedding of doxygen content through rst rendered files. Add openamp and libmetal breathe projects to conf.py to integrate breathe to both library generated doxygen content. refer https://breathe.readthedocs.io/en/latest/index.html This commit relies on having doc/Doxyfile.in modified in openamp and libmetal repositories to include GENERATE_XML = YES

Add sphinxcontrib.doxylink extension to requirements.txt to allow linking, in rst files, to generated doxygen files of submodule repositories. refer https://github.com/sphinx-contrib/doxylink https://sphinxcontrib-doxylink.readthedocs.io This commit relies on having doc/Doxyfile.in modified in openamp and libmetal repositories to include GENERATE_TAGFILE = <filename as in doxylink dictionary of conf.py>

adjust the Porting guide for Remoteproc to use breathe's doxygenfunction and doxygenstruct to embed doxygen code documentation of the remoteproc_ops structure and functions using it. Also add doxylink link to the same struct in case anyone wants to look at all the doxygen documentation.

add highlighted code-block for virtio example. code-block requires two spaces for code post tag.

add links for virtio and remote proc driver

…rences the data_structures file is a markdown (md) file in open-amp repository which uses code within the file to demonstrate datastructures. Review comments were to use doxygen linking, so use breathe and doxylink in a new file within readthedocs to achieve the same reference but through linking which will maintain itself as long as doxygen comments are maintained in open-amp repo.

point and new data structures and move it to under design docs and move the porting guide as its own section rather than under library users guide.

…erences the remoteproc-design file is a markdown (md) file in open-amp repository which uses code within the file to demonstrate APIs. Review comments were to use doxygen linking, so use breathe and doxylink in a new file within readthedocs to achieve the same references but through embedding which will maintain itself as long as doxygen comments are maintained in open-amp repo.

the rpmsg-design file is a markdown (md) file in open-amp repository which uses code within the file to demonstrate APIs. Review comments were to use doxygen linking, so use breathe and doxylink in a new file within readthedocs to achieve the same references but through embedding which will maintain itself as long as doxygen comments are maintained in open-amp repo.

remove sentence as design documents have moved to readthedocs to allow embedding of doxygen content via breathe extension to readthedocs.

add line limit of 100 characters per review feedback

arnopo · 2025-07-01T12:43:46Z

@@ -0,0 +1,136 @@
+Remoteproc Design Document


meeting done to discuss the design base on breathe:
decision:

integrate this PR and move forward with breathe

move md and image documentation from openamp repository to openamp-doc repository and convert file in RST.

arnopo · 2025-07-01T12:48:14Z

+.. doxygenstruct:: vring
+   :members:
+
+Refer also :openamp_doc_link:`vring <vring>` documentation and `vring code implementation <https://github.com/OpenAMP/open-amp/blob/main/lib/include/openamp/virtio_ring.h>`_.


to address in a separate PR, I created the issue #63

arnopo requested review from arnopo, danmilea, edmooring, tnmysh and wmamills March 24, 2025 08:23

sipke force-pushed the feature/add-breathe-and-doxylink branch from 0533302 to 293a36e Compare April 28, 2025 05:47

wmamills mentioned this pull request May 7, 2025

demos: update NXP reference boards page #56

Merged

edmooring approved these changes May 16, 2025

View reviewed changes

sipke force-pushed the feature/add-breathe-and-doxylink branch from 293a36e to 99be20f Compare May 19, 2025 04:46

sipke force-pushed the feature/add-breathe-and-doxylink branch from 99be20f to f1cd0f7 Compare May 26, 2025 03:36

sipke force-pushed the feature/add-breathe-and-doxylink branch from f1cd0f7 to 06263c7 Compare June 9, 2025 06:04

arnopo reviewed Jun 10, 2025

View reviewed changes

sipke force-pushed the feature/add-breathe-and-doxylink branch from 06263c7 to 164621f Compare June 11, 2025 00:28

arnopo reviewed Jun 18, 2025

View reviewed changes

Sipke Vriend added 11 commits June 23, 2025 09:41

docs:porting_guide: add code-block for c highlighting

7b4d841

add highlighted code-block for virtio example. code-block requires two spaces for code post tag.

docs:porting_guide: add links

f3e0d01

add links for virtio and remote proc driver

docs: use new data_structures and promote porting guide to own section

af84672

point and new data structures and move it to under design docs and move the porting guide as its own section rather than under library users guide.

protocol_details: design docs have moved to readthedocs

16dce85

remove sentence as design documents have moved to readthedocs to allow embedding of doxygen content via breathe extension to readthedocs.

contributing: line limit to 100

7546e7c

add line limit of 100 characters per review feedback

sipke force-pushed the feature/add-breathe-and-doxylink branch from 164621f to 7546e7c Compare June 23, 2025 00:13

arnopo approved these changes Jul 1, 2025

View reviewed changes

arnopo merged commit a2409d0 into OpenAMP:main-next Jul 1, 2025
1 check passed

This was referenced Jul 1, 2025

doxygen content should be integrated into sphinx content #19

Closed

Documentation Update and Restructure : remaining tasks #38

Closed

Conversation

sipke commented Mar 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

arnopo commented Mar 25, 2025

Uh oh!

sipke commented Mar 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

edmooring left a comment

Choose a reason for hiding this comment

Uh oh!

sipke commented May 19, 2025

Uh oh!

sipke commented May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

arnopo commented May 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sipke Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sipke Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arnopo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sipke commented Mar 24, 2025 •

edited

Loading

sipke commented Mar 26, 2025 •

edited

Loading

sipke commented May 26, 2025 •

edited

Loading

sipke Jun 10, 2025 •

edited

Loading

sipke Jun 10, 2025 •

edited

Loading