fix(docs): fix most sphinx warnings #6916

vwheeler63 · 2024-09-23T15:47:19Z

In PR #6542 Kevin made a number of valuable changes to .RST files the eliminate
a large number of Sphinx errors that he encountered. Those were cherry picked
and reviewed and brought here. On a test docs generation a few more cropped
up and they were handled here as well.

What it leaves UNhandled because it has something to do with breathe that I don't
quite get yet is a large number of warnings that look like this (all "Cannot find file"):

<tmpdir>\API/others/gridnav/lv_gridnav.rst:8: WARNING: doxygenfile: Cannot find file "lv_gridnav.h

and

<tmpdir>\widgets\led.rst:7: WARNING: duplicate label lv_led, other instance in <tmpdir>\API/widgets/led/lv_led.rst

which appears to be caused by an error in whatever preps the API .RST files for Sphinx. In the above example, I believe either this file: <tmpdir>\API/widgets/led/lv_led.rst or this file <tmpdir>\widgets\led.rst is in error, not sure which.

I am hoping Kevin ( @kdschlosser ) might know what to do with these.

Notes

Update the Documentation if needed. n/a
Add Examples if relevant. n/a
Add Tests if applicable. n/a
If you added new options to lv_conf_template.h run lv_conf_internal_gen.py and update Kconfig. n/a
Run scripts/code-format.py (astyle v3.4.12 needs to installed by running cd scripts; ./install_astyle.sh) and follow the Code Conventions. n/a
Mark the Pull request as Draft while you are working on the first version, and mark is as Ready when it's ready for review. (is ready)
When changes were requested, re-request review to notify the maintainers. Done.
Help us to review this Pull Request! Anyone can approve or request changes.

vwheeler63

I have reviewed each file and can assert that it is as it needs to be for correct formatting and eliminating Sphinx errors. The lv_conf_template.h and lv_conf_internal.h are minor formatting updates that got overlooked previously.

kdschlosser · 2024-09-23T16:47:28Z

the duplicate labels are happening because there is a duplicate reference. It is a crappy error/warning that sphinx uses and it really needs to be changed upstream in sphinx.

If you look at the hard coded .rst files in the docs directory you will see .. _some-reference: above the header. That is a "label" It is actually an anchor for a reference. In the example you have posted above the problem needs to be fixed in the generation code for the API...

lvgl/docs/doc_builder.py

Line 1099 in 0227f7d

f.write('.. _{0}:'.format(name))

needs to be changed to

f.write('.. _{0}_h:'.format(name))

and

lvgl/docs/doc_builder.py

Line 1334 in 0227f7d

':ref:`{0}`\n'.format(inc)

needs to be changed to

':ref:{0}_h\n'.format(inc)

That will stop the label collisions.

There has been a massive change to the API naming and that includes filenames. If the hard coded .rst files have specific information that aligns with a specific piece of the API the filename omf the .rst file MUST match the header filename that the information is about. This is what links the hard coded .rst file with the proper API section in the documentation.

kdschlosser · 2024-09-23T16:57:31Z

the problem with the not finding files is the reason why I went looking for a breathe replacement. Breathe is designed to read one header file at a time. The problem with that is the use of a configuration header file that exposes the various portions of the API. In order to allow everything to work properly each and every single header file in LVGL would need to include the config header file. How LVGL works currently is it includes the config header file a single time when lvgl.h is included and the config settings propagate because the compiler sees the macros from the config file because that file was loaded. But if using the compiler to read a single header file that information is now unavailable. It is a limitation of breathe and it is something that is not going to be fixed upstream in breathe unless the guy gets paid to fix it.

The other issue with breathe is it doesn't use full paths when generating documentation using the .. doxygenfile:: directive which is what the doc build system is using. So if you have header files that have the same name you run into problems.

vwheeler63 · 2024-09-24T07:17:42Z

@FASTSHIFT

changed the title Fix Most Sphinx Warnings fix(docs): fix most sphinx warnings

Got it. 😉

vwheeler63 · 2024-09-24T07:20:02Z

@kisvegabor Ready with cherry-picked PR if you hadn't seen this already. Co-authored by Kevin if that part is not automated.

vwheeler63 · 2024-09-24T09:25:30Z

The duplicate labels are happening because...

Thank you for the tips! It works!

If the hard coded .rst files have specific information that aligns with a specific piece of the API the filename of the .rst file MUST match the header filename that the information is about.

Got it. Handled.

The problem with the not finding files is the reason why I went looking for a breathe replacement.

Let's move this to #6924

kisvegabor

Thank you Victor and Kevin.
Having these in place would make further work on the docs simpler and lighter.

vwheeler63 · 2024-09-24T12:38:24Z

Thank you Victor and Kevin. Having these in place would make further work on the docs simpler and lighter.

I think we can eliminate all the sphinx warnings! As I type this, there is only one type left, and I know there was a point a couple of months ago when I was generating documentation without this type of error, so I think it is possible.

liamHowatt

Thanks!

docs/README.md

docs/integration/chip/nxp.rst

liamHowatt · 2024-09-26T10:13:19Z

Thanks! Looks like there are merge conflicts.

vwheeler63 · 2024-09-26T10:26:54Z

Thanks! Looks like there are merge conflicts.

I'm on it.

(cherry picked from commit cb25568)

(cherry picked from commit 46713c0)

(cherry picked from commit 5b11c5b) # Conflicts: # docs/integration/ide/pc-simulator.rst

(cherry picked from commit 57bcff3) # Conflicts: # docs/overview/renderers/arm2d.rst # docs/widgets/label.rst

(cherry picked from commit b224555) # Conflicts: # docs/porting/indev.rst

(cherry picked from commit 0b6abf7)

Guidelines for updating documentation. (cherry picked from commit dcb9725)

Co-authored-by: Liam <30486941+liamHowatt@users.noreply.github.com>

vwheeler63 · 2024-09-26T11:35:21Z

@liamHowatt @kisvegabor

Conflicts handled and re-submitted. FYI, the underline lengths previously discussed also match the titles in this one.

kisvegabor · 2024-09-27T05:08:17Z

There is a new conflict. 🙁

# Conflicts: # docs/overview/renderers/arm2d.rst

vwheeler63 · 2024-09-27T07:36:10Z

There is a new conflict. 🙁

No problem! Conflict fixed & re-submitted.

liamHowatt

Thank you. I did not check thoroughly. I will assume the conflict resolution was ok 🙂

vwheeler63 · 2024-09-27T11:44:12Z

Thank you. I did not check thoroughly. I will assume the conflict resolution was ok 🙂

Thank you. Indeed. @kisvegabor Over to you, kind sir!

kisvegabor · 2024-09-30T12:57:06Z

Thank you!
I found these long dash lines in an MD files a little bit odd, but let's merge this PR now and fix it later.

kdschlosser · 2024-09-30T13:06:21Z

@kisvegabor

The long dashed lines get changed into a horizontal line or hrule

kisvegabor · 2024-10-02T11:28:19Z

The long dashed lines get changed into a horizontal line or hrule

I know, but I think we don't need these custom decorations, but for consistency we should rely on the markdown viewer's style.

@paragraph

- Remove horizontal rules as requested. - Grammar corrected. - Edited for clarity. - Artificial line wraps (as `.md` files produce when the internal text is readable) removed, so that line wrapping will occur with browser width. - Stated requirement for 2 blank lines after lists and code blocks removed as these do not always improve readability. - 2 blank lines over headings requirement allowed to remain, since these always improve readability. - File content examples outdented to left edge to more accurately portray file content. - Several clarifications and added. - Accurate reStructuredText vocabulary used. - Error of only one colon after `.. code-block::` directive fixed (all directives other than link targets must have 2 colons). - "Paragraph" clarified as "Sub Sub Sub Section" since not everyone will know Doxygen's @paragraph command marks the lowest-level Doxygen section heading. - Examples for linking to code in API pages clarified with solutions. Addresses request expressed by Gábor at end of PR lvgl#6916.

vwheeler63 · 2024-10-02T19:06:30Z

The long dashed lines get changed into a horizontal line or hrule

I know, but I think we don't need these custom decorations, but for consistency we should rely on the markdown viewer's style.

Done! PR #6992

kdschlosser · 2024-10-02T19:49:01Z

I know, but I think we don't need these custom decorations, but for consistency we should rely on the markdown viewer's style.

markdown viewer or ReST viewer?

vwheeler63 · 2024-10-02T22:51:31Z

I know, but I think we don't need these custom decorations, but for consistency we should rely on the markdown viewer's style.

markdown viewer or ReST viewer?

Markdown.

vwheeler63 force-pushed the fix/fix_most_sphinx_warnings_1 branch 3 times, most recently from 000b5bc to 1a73037 Compare September 23, 2024 16:28

vwheeler63 commented Sep 23, 2024

View reviewed changes

vwheeler63 force-pushed the fix/fix_most_sphinx_warnings_1 branch from 1a73037 to 4f63e36 Compare September 23, 2024 16:43

FASTSHIFT changed the title ~~Fix Most Sphinx Warnings~~ fix(docs): fix most sphinx warnings Sep 24, 2024

vwheeler63 mentioned this pull request Sep 24, 2024

Docs Generation: breathe/sphinx Warning: doxygenfile: Cannot find file "lv_button.h #6924

Open

kisvegabor requested a review from liamHowatt September 24, 2024 11:57

kisvegabor previously approved these changes Sep 24, 2024

View reviewed changes

kisvegabor added the 👀 Review needed Anyone can review a PR label Sep 24, 2024

liamHowatt reviewed Sep 25, 2024

View reviewed changes

docs/README.md Outdated Show resolved Hide resolved

docs/README.md Outdated Show resolved Hide resolved

docs/README.md Outdated Show resolved Hide resolved

docs/integration/chip/nxp.rst Outdated Show resolved Hide resolved

vwheeler63 dismissed kisvegabor’s stale review via 8836131 September 25, 2024 12:13

kisvegabor previously approved these changes Sep 26, 2024

View reviewed changes

liamHowatt reviewed Sep 26, 2024

View reviewed changes

docs/integration/chip/nxp.rst Outdated Show resolved Hide resolved

vwheeler63 dismissed kisvegabor’s stale review via bce37ef September 26, 2024 09:56

liamHowatt previously approved these changes Sep 26, 2024

View reviewed changes

vwheeler63 force-pushed the fix/fix_most_sphinx_warnings_1 branch from bce37ef to 0b7c5c7 Compare September 26, 2024 10:30

kdschlosser added 5 commits September 26, 2024 04:33

Fixes doc WARNING: Unparseable C cross-reference

4814262

(cherry picked from commit cb25568)

Fixes doc WARNING: Unparseable C++ cross-reference

8806db3

(cherry picked from commit 46713c0)

Fixes doc WARNING: Bullet list ends without a blank line

ebdda96

(cherry picked from commit 5b11c5b) # Conflicts: # docs/integration/ide/pc-simulator.rst

Fixes doc ERROR: Unexpected indentation

0d8397a

(cherry picked from commit 57bcff3) # Conflicts: # docs/overview/renderers/arm2d.rst # docs/widgets/label.rst

Fixes doc WARNING: Inline literal start-string without end-string

4ea5605

(cherry picked from commit b224555) # Conflicts: # docs/porting/indev.rst

vwheeler63 and others added 10 commits September 26, 2024 05:12

code formatting and standardizing use of .. code-block::

f233ada

(cherry picked from commit 0b6abf7)

adds docs/README.md

78f59c3

Guidelines for updating documentation. (cherry picked from commit dcb9725)

fix: fix formatting errors

0b11489

fix: indentation errors

642d78f

fix: Fix most Sphinx warnings and misc formatting

b5de46f

Update docs/README.md

36fcb0b

Co-authored-by: Liam <30486941+liamHowatt@users.noreply.github.com>

Update docs/README.md

e80b317

Co-authored-by: Liam <30486941+liamHowatt@users.noreply.github.com>

Update docs/README.md

b38d3f5

Co-authored-by: Liam <30486941+liamHowatt@users.noreply.github.com>

fix: error from outdated code in cherry-pick

22ca4ba

fix: another error from outdated cherry-pick

45f27e0

vwheeler63 dismissed liamHowatt’s stale review via 45f27e0 September 26, 2024 11:13

vwheeler63 force-pushed the fix/fix_most_sphinx_warnings_1 branch from 0b7c5c7 to 45f27e0 Compare September 26, 2024 11:13

Merge branch 'master' into fix/fix_most_sphinx_warnings_1

d67bf88

# Conflicts: # docs/overview/renderers/arm2d.rst

liamHowatt approved these changes Sep 27, 2024

View reviewed changes

liamHowatt requested a review from kisvegabor September 30, 2024 12:38

kisvegabor approved these changes Sep 30, 2024

View reviewed changes

kisvegabor merged commit 0458acd into lvgl:master Sep 30, 2024
21 checks passed

vwheeler63 deleted the fix/fix_most_sphinx_warnings_1 branch September 30, 2024 13:09

vwheeler63 mentioned this pull request Oct 2, 2024

fix: ./docs/README.md reworked to handle several things #6992

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(docs): fix most sphinx warnings #6916

fix(docs): fix most sphinx warnings #6916

fix(docs): fix most sphinx warnings #6916

fix(docs): fix most sphinx warnings #6916

Conversation

Notes

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment