Open Bug 1536103 Opened 2 years ago Updated 1 day ago

Fix sphinx warnings in `mach doc` and make them fail the build

Categories

(Firefox Build System :: Generated Documentation, enhancement)

enhancement
Not set
normal

Tracking

(Not tracked)

ASSIGNED

People

(Reporter: ahal, Assigned: championshuttler)

References

(Blocks 1 open bug)

Details

(Keywords: leave-open)

Attachments

(11 files, 1 obsolete file)

47 bytes, text/x-phabricator-request
Details | Review
47 bytes, text/x-phabricator-request
Details | Review
47 bytes, text/x-phabricator-request
Details | Review
47 bytes, text/x-phabricator-request
Details | Review
47 bytes, text/x-phabricator-request
Details | Review
47 bytes, text/x-phabricator-request
Details | Review
47 bytes, text/x-phabricator-request
Details | Review
47 bytes, text/x-phabricator-request
Details | Review
47 bytes, text/x-phabricator-request
Details | Review
47 bytes, text/x-phabricator-request
Details | Review
47 bytes, text/x-phabricator-request
Details | Review

If you run mach doc there are tons of WARNINGS that are spewed to stdout. We should fix them all and configure sphinx-build to fail on warnings to prevent new ones from being added in the future. This is likely a large task, so we may want to turn this into a meta bug and file dependents to start fixing this little by little.

This is also closely related to bug 1527361, as that will catch and prevent many of the same issues. I think doing both of these things are still worthwhile however.

Summary: Fix sphinx warnings in `mach doc` → Fix sphinx warnings in `mach doc` and make them fail the build

Great, thanks Shivam!

I'm setting leave-open which means the bug will remain open after patches land. This way if you wish to keep working on this issue, you can submit multiple patches on top of one another until you either want to stop or all of the warnings have been fixed. Please let me know if you want to continue working on this or not.

Assignee: nobody → shivams2799
Status: NEW → ASSIGNED
Keywords: leave-open
Pushed by ahalberstadt@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/5d251a7e6031
Fix Sphinx Warning - Title Underline too short  in 'mach doc'. r=ahal
https://hg.mozilla.org/projects/ash/rev/5d251a7e6031cd707c83c9b22425610d3e056f1d
Bug 1536103 - Fix Sphinx Warning - Title Underline too short  in 'mach doc'. r=ahal
Attachment #9072775 - Attachment description: Bug 1536103 - Fix sphinSphinx Warning - Unexpected indentation (1). r=ahal → Bug 1536103 - Fix Sphinx Warning - Unexpected indentation (1). r=ahal
Attachment #9072775 - Attachment description: Bug 1536103 - Fix Sphinx Warning - Unexpected indentation (1). r=ahal → Bug 1536103 - Fix sphinSphinx Warning - Unexpected indentation (1). r=ahal
Attachment #9072775 - Attachment description: Bug 1536103 - Fix sphinSphinx Warning - Unexpected indentation (1). r=ahal → Bug 1536103 - Fix Sphinx Warning - Unexpected indentation (1). r=ahal
Attachment #9072775 - Attachment description: Bug 1536103 - Fix Sphinx Warning - Unexpected indentation (1). r=ahal → Bug 1536103 - Fix sphinSphinx Warning - Unexpected indentation (1). r=ahal
Attachment #9072775 - Attachment description: Bug 1536103 - Fix sphinSphinx Warning - Unexpected indentation (1). r=ahal → Bug 1536103 - Fix Sphinx Warning - Unexpected indentation (1). r=ahal
Pushed by ahalberstadt@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/97b7600d3c92
Fix Sphinx Warning - Unexpected indentation (1). r=ahal
https://hg.mozilla.org/integration/autoland/rev/61c481e2d2e8
Fix Sphinx Warning - Title Underline too short in 'mach doc' (2). r=ahal
https://hg.mozilla.org/integration/autoland/rev/8a205b411e7e
Fix various Sphinx Warning in 'mach doc' (3). r=ahal
Pushed by ahalberstadt@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/61ef4dac17e1
Fix various Sphinx Warning in 'mach doc' (4). r=ahal

Pushed by apavel@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/fb0ae6ca7322
Fix Sphinx Warning for not referenced hyperlinks. r=ahal

Keywords: checkin-needed
Keywords: leave-open

Comment on attachment 9110384 [details]
Bug 1536103 - Remove unused file from marionatte docs. r=sylvestre,ahal

Revision D54045 was moved to bug 1598279. Setting attachment 9110384 [details] to obsolete.

Attachment #9110384 - Attachment is obsolete: true
Pushed by hskupin@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/fb6fa343472b
Add files to marionatte toctree. r=marionette-reviewers,ato
Pushed by sledru@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/b5c6e2ad46e7
Update Piplock file for mach doc command. r=sylvestre
Pushed by sledru@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/97dfb457a8b3
Fix links for GeckoView landing page.r=sylvestre

I suspect this isn't going to be very practical unless we find a way to silence the "duplicate label" warnings. My gut is that it's unreasonable to force every label in the entire tree to be uniquely named (eg lots of sub-docs have labels like "Examples" and that's entirely reasonable). Excitingly, so far, my searches on the web seem to suggest that this is considered a "feature" of Sphinx and I haven't yet found a trivial way to suppress them. Though I suppose we could teach the harness to ignore them. In some ways, part of the problem seems to be Sphinx' transclusion model that pretends that things are just One Big Document. But maybe we could be using the transclusion model more effectively...

(In reply to Dan Mosedale (:dmose, :dmosedale) from comment #28)

I suspect this isn't going to be very practical unless we find a way to silence the "duplicate label" warnings. My gut is that it's unreasonable to force every label in the entire tree to be uniquely named (eg lots of sub-docs have labels like "Examples" and that's entirely reasonable). Excitingly, so far, my searches on the web seem to suggest that this is considered a "feature" of Sphinx and I haven't yet found a trivial way to suppress them. Though I suppose we could teach the harness to ignore them. In some ways, part of the problem seems to be Sphinx' transclusion model that pretends that things are just One Big Document. But maybe we could be using the transclusion model more effectively...

Agreed.
Also there are some rst files not indexed and thus producing warnings. What should happen to them?

Pushed by sledru@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/7da4a25e3637
Fixed mach doc warnings.r=firefox-source-docs-reviewers,championshuttler,sylvestre
Pushed by sledru@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/bed226f8bccd
Removed some unused devtools in tree placeholder documentation.r=firefox-source-docs-reviewers,sylvestre
You need to log in before you can comment on or make changes to this bug.