Correct some doxygen/sphinx warnings or errors.#721
Correct some doxygen/sphinx warnings or errors.#721zeddii merged 4 commits intodevicetree-org:masterfrom
Conversation
docs/amd/linux/source/index.rst
Outdated
| Welcome to Linux Device Tree Generation for AMD SOCs using Lopper and SDT's documentation! | ||
| =========================================================================================== | ||
| Linux Device Tree Generation for AMD SOCs using Lopper and SDT's | ||
| ================================================================ |
There was a problem hiding this comment.
I'd prefer to leave this as-is, there's different consumers of this, and I'm not fond of tweaking it to suit one over the others.
zeddii
left a comment
zeddii
left a comment
There was a problem hiding this comment.
You'll need to be more specific here.
How does this change the output of the docs ? What's the old versus the new look like ?
I have no idea about the open-amp readthedocs, so using that as a reason for a change unfortunately doesn't mean anything to me.
zeddii
left a comment
zeddii
left a comment
There was a problem hiding this comment.
You'll need to be more specific here.
How does this change the output of the docs ? What's the old versus the new look like ?
I have no idea about the open-amp readthedocs, so using that as a reason for a change unfortunately doesn't mean anything to me.
| Basic Workflow (without board-specific device-tree): | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| Gen 2 Basic Workflow (without board-specific device-tree): | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
There was a problem hiding this comment.
I know very little about sphinx (outside of occasioning editing file and generating with it).
What is the significance of "Gen 2" in the updated lines ?
There was a problem hiding this comment.
You can enable autosectionlabel generation when using sphinx/doxygen. i.e. for every heading in an rst or md file a label is created based on the heading. https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html
Where the autosectionlabel can be used in external other rst files to reference/link these headings directly, without having to add manual labels.
Unfortunately sphinx does not prefix subheadings with the previous heading level so any subheading which is the same in multiple higher level headings is a duplicate label.
What you had is cleaner (more readable), so maybe not a good idea to change, but anyone using autosectionlabel will receive a warning currently if enabled.
The Gen 2 was just propogated from the top level heading "For Versal Gen 2 Platform:"
|
Can't do it at moment, but I will rework the branch to target "actual" documentation errors, and remove the format/layout change ones where there is a sphinx warning but arguably not an issue. In terms of how things change, apart from the obvious ones where the title changed, there were only really heading level changes, where subheadings were slightly smaller, and each file receive a top level heading. The main difference is the sphinx build output generates less warnings. |
Correct table formatting to fix sphinx error ERROR: Malformed table Signed-off-by: Sipke Vriend <sipke@direktembedded.com>
sipke
force-pushed
the
feature/remove-toc-not-included-warnings
branch
from
3285e5f to
3b0b972
Compare
Add a delimiter to the bold/* emphasis character to avoid the warning WARNING: Inline emphasis start-string without end-string Signed-off-by: Sipke Vriend <sipke@direktembedded.com>
…y line the - (dash) for the bullet point was to left of Optional tag making the sphinx document generator think it is a new line rather than bullet point, so move it to the left to correct the warning: WARNING: Bullet list ends without a blank line Signed-off-by: Sipke Vriend <sipke@direktembedded.com>
Change the H3 headings after an H1 heading to H3 to remove the sphinx warning: WARNING: Non-consecutive header level increase; H1 to H3 [myst.header] Signed-off-by: Sipke Vriend <sipke@direktembedded.com>
sipke
force-pushed
the
feature/remove-toc-not-included-warnings
branch
from
13eb169 to
2c9142c
Compare
sipke
changed the title
2 participants
This pull request (PR) corrects some doxygen/sphinx warnings or errors.
Most of these have no direct effect on documentation output, except one where heading levels changed, so the size of the heading is likely to increase for the subheading.
This is a second round of changes focusing on documentation generation errors rather than layout preferences to address initial review comments.
These warnings/errors were found during attempts to further integrate submodules into openamp-docs via PR OpenAMP/openamp-docs#82.