Feature/remove toc not included warnings#721
Feature/remove toc not included warnings#721sipke wants to merge 8 commits intodevicetree-org:masterfrom
Conversation
To integrate these readme files into open-amp readthedocs the layout as created by table of contents is better when the file has a title so introduce a title and change H1 headings to H2. Signed-off-by: Sipke Vriend <sipke@direktembedded.com>
To integrate this index file into open-amp readthedocs reduce the title length and wording to suit a table of contents heading. Signed-off-by: Sipke Vriend <sipke@direktembedded.com>
To integrate this index file into open-amp readthedocs reduce the depth of table of contents to avoid excessive levels. Signed-off-by: Sipke Vriend <sipke@direktembedded.com>
Correct table formatting to fix sphinx error ERROR: Malformed table Signed-off-by: Sipke Vriend <sipke@direktembedded.com>
Clarify headings to remove duplicate labels sphinx warning. WARNING: duplicate label Signed-off-by: Sipke Vriend <sipke@direktembedded.com>
Add empty line to remove sphinx warning WARNING: Bullet list ends without a blank line Signed-off-by: Sipke Vriend <sipke@direktembedded.com>
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>
…hinx Clarify headings to remove duplicate labels sphinx warning. WARNING: duplicate label Signed-off-by: Sipke Vriend <sipke@direktembedded.com>
| 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. |
2 participants
This pull request (PR) supports openamp-docs PR OpenAMP/openamp-docs#82, whose intent is to integrate git submodule documentation into openamp readthedocs.
Any markdown (.md) or restructured text (.rst) not included in openamp-docs show up as sphinx documentation warnings "toc not included", so these are either introduced into readthedocs or hidden if not relevant.
Additionally any new sphinx warnings are addressed.