Fix references in rst to md files #65
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
added 30 commits
January 15, 2025 10:17
Provide a succinct introduction to AMP with comparison to SMP to lead into a new section detailing the 'Fundamental' parts that OpenAMP is addressing with the intent of leading into which parts are implemented by what part of OpenAMP architecture which is the next section. Parts taken from 'System Wide Considerations'.
provide a high level architecture and diagram of a chained topology and reference components to the amp fundamentals they serve.
restructure and reword with aim of flowing from intro, to architectural overview through to project and member info.
images were not rendering correctly
adjust after review from readthedocs rendering
to help the reader locate the components repeat the diagrams highlighting the references components per section.
so we can reference the endpoint information from other pages, add a reference in the rpmsg doc file
in migrating demo documentation start a new section via an index page which will hold a top down architectural description of the demos.
use the architecture overview diagram to exemplify the demo and the components used.
To allow for restructure of demos to have example explanations and then links to implementation on reference boards, create new document to link to reference boards.
use source for code, and implementation for reference boards in headings.
Reference boards have move to own section so remove from original index. Leave the other sections in situ still as they have not been captured elsewhere yet.
add intro diagram and initial introduction for sample client for the RPMsg multi services demo.
although technically it isn't a reference board, it is a demonstration platform so add a page under reference boards for Inter Process Demos.
These TI boards are supported out-of-box by the latest Zephyr and make use of OpenAMP for IPC. Document these boards. Signed-off-by: Andrew Davis <[email protected]>
The example cores are common to many platforms, no need to specify a platform for each. While here update the TI example SoC to something more recent and currently supported by the OpenAMP project. Also add an example for an OpenAMP supported ST device. Signed-off-by: Andrew Davis <[email protected]>
Most of this page is in governance, so remove most and leave only more specific links to other sections providing more specific details on how to contribute. Refer issue 38: OpenAMP#38 Addressing review comments: * Avoid duplication with https://www.openampproject.org/governance/ in this pages. to determine if a part of the gouvernance should be moved ghere * no roadmap defined, to remove chapter * no platform maintainer defined, to remove chapter and/or rewrite according to gouvernance page
Review change to change wording to "propose your platform as a reference platform" Add some changes and additions suggested by nathalie-ckc
Address issue OpenAMP#51 to remove uncommon acronyms from Operating Environments section of Overview.
Address issue OpenAMP#51 to remove uncommon acronyms from Operating Environments section of Overview.
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
Set automatically generated heading anchors to 4 levels, i.e. h1,h2,h3,h4 This will ensure markdown file headings generate an automatic label which can be referenced from readthedocs files to avoid needing hardcoded URLs. Also enable file in anchor reference to avoid issue with duplicate headers in different files Refer https://myst-parser.readthedocs.io/en/stable/syntax/optional.html#syntax-header-anchors https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html
Use the generated link to openamp-system-reference examples/zephyr readme initialization section to make a dynamic link rather than URL.
Use the generated link to openamp-system-reference examples/linux/rpmsg-echo-test/README 'run the demo section' to make a dynamic link rather than URL.
Use the generated link to open-amp/README inter process section to make a dynamic link rather than URL.
Use the generated link to open-amp/READMEopenamp-system-reference/examples/zephyr/rpmsg_multi_services/README sections to provide dynamic link rather than URL.
Use the generated link to lopper/README-architecture: lopper processing flow: sections to provide dynamic link rather than URL.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
To address #59 enable automatically generated header anchor in sphinx conf.py file including adding the file as prefix to the anchor to ensure that if there are duplicates between files, the anchor remains unique.
Then modify links in readthedocs which reference souce repository markdown files so the document is dynamically linked rather than using the https link to the github file.
This change does not require any modifications to existing source repository markdown files.
Refer comment in #59 for more details/explanation.