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

Status: RESOLVED FIXED

(Developer Infrastructure :: Source Documentation, enhancement)

Description

[Andrew Halberstadt [:ahal]]

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.

Comment 1

[Shivam Singhal [ :championshuttler ]]

Attachment: Bug 1536103 - Fix Sphinx Warning - Title Underline too short in 'mach doc'. r=ahal

Comment 2

[Andrew Halberstadt [:ahal]]

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.

Comment 3

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/5d251a7e6031
Fix Sphinx Warning - Title Underline too short  in 'mach doc'. r=ahal

Comment 4

[Stefan Hindli [:stefan_hindli]]

https://hg.mozilla.org/mozilla-central/rev/5d251a7e6031

Comment 5

[Peter Van der Beken [:peterv]]

https://hg.mozilla.org/projects/ash/rev/5d251a7e6031cd707c83c9b22425610d3e056f1d
Bug 1536103 - Fix Sphinx Warning - Title Underline too short  in 'mach doc'. r=ahal

Comment 6

[Shivam Singhal [ :championshuttler ]]

Attachment: Bug 1536103 - Fix Sphinx Warning - Unexpected indentation (1). r=ahal

Comment 7

[Shivam Singhal [ :championshuttler ]]

Attachment: Bug 1536103 - Fix Sphinx Warning - Title Underline too short in 'mach doc' (2). r=ahal

Depends on D35304

Comment 8

[Shivam Singhal [ :championshuttler ]]

Attachment: Bug 1536103 - Fix various Sphinx Warning in 'mach doc' (3). r=ahal

Depends on D35309

Comment 9

[Pulsebot]

Pushed by [e-mail]:
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

Comment 10

[Stefan Hindli [:stefan_hindli]]

https://hg.mozilla.org/mozilla-central/rev/97b7600d3c92
https://hg.mozilla.org/mozilla-central/rev/61c481e2d2e8
https://hg.mozilla.org/mozilla-central/rev/8a205b411e7e

Comment 11

[Shivam Singhal [ :championshuttler ]]

Attachment: Bug 1536103 - Fix various Sphinx Warning in 'mach doc' (4). r=ahal

Comment 12

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/61ef4dac17e1
Fix various Sphinx Warning in 'mach doc' (4). r=ahal

Comment 13

[Oana Pop-Rus]

https://hg.mozilla.org/mozilla-central/rev/61ef4dac17e1

Comment 14

[Shivam Singhal [ :championshuttler ]]

Attachment: Bug 1536103 - Fix Sphinx Warning for not referenced hyperlinks. r=ahal

Comment 15

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/fb0ae6ca7322
Fix Sphinx Warning for not referenced hyperlinks. r=ahal

Comment 16

[Andrei Ciure[:aciure]]

https://hg.mozilla.org/mozilla-central/rev/fb0ae6ca7322

Comment 17

[Shivam Singhal [ :championshuttler ]]

Attachment: Bug 1536103 - Remove unused file from marionatte docs. r=sylvestre,ahal

Comment 18

[Shivam Singhal [ :championshuttler ]]

Attachment: Bug 1536103 - Add files to marionatte toctree. r=sylvestre,ahal

Depends on D54045

Comment 19

[Phabricator Automation]

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.

Comment 20

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/fb6fa343472b
Add files to marionatte toctree. r=marionette-reviewers,ato

Comment 21

[Andrei Ciure[:aciure]]

https://hg.mozilla.org/mozilla-central/rev/fb6fa343472b

Comment 22

[Shivam Singhal [ :championshuttler ]]

Attachment: Bug 1536103 - Update Piplock file for mach doc command. r?sylvestre

Comment 23

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/b5c6e2ad46e7
Update Piplock file for mach doc command. r=sylvestre

Comment 24

[Raul Gurzau (:RaulG)]

https://hg.mozilla.org/mozilla-central/rev/b5c6e2ad46e7

Comment 25

[Shivam Singhal [ :championshuttler ]]

Attachment: Bug 1536103 - Fix links for GeckoView landing page.r=sylvestre,ahal

Comment 26

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/97dfb457a8b3
Fix links for GeckoView landing page.r=sylvestre

Comment 27

[Stefan Hindli [:stefan_hindli]]

https://hg.mozilla.org/mozilla-central/rev/97dfb457a8b3

Comment 28

[Dan Mosedale (:dmosedale, :dmose)]

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...

Comment 29

[Anurag Aggarwal]

Attachment: Bug 1536103 - Fixed mach doc warnings.r?#firefox-source-docs-reviewers

Comment 30

[Anurag Aggarwal]

(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?

Comment 31

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/7da4a25e3637
Fixed mach doc warnings.r=firefox-source-docs-reviewers,championshuttler,sylvestre

Comment 32

[Daniel Varga [:dvarga]]

https://hg.mozilla.org/mozilla-central/rev/7da4a25e3637

Comment 33

[Anurag Aggarwal]

Attachment: Bug 1536103 - Removed some unused devtools in tree placeholder documentation.r?#firefox-source-docs-reviewers

Comment 34

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/bed226f8bccd
Removed some unused devtools in tree placeholder documentation.r=firefox-source-docs-reviewers,sylvestre

Comment 35

[Alexandru Michis [:malexandru]]

https://hg.mozilla.org/mozilla-central/rev/bed226f8bccd

Comment 36

[Greg Tatum [:gregtatum]]

fail on warnings to prevent new ones from being added in the future

I wanted to give a little bit of feedback that this issue creates a lot of friction for adding new documentation. In Bug 1641000 I wrote some new docs. I introduced quite a few errors initially, and it took some effort to remove them given the amount of output.

Comment 37

[Sylvestre Ledru [:Sylvestre]]

creates a lot of friction

Agreed but fixing tones of the warning isn't fun for anyone ... As you can see, many of us have been working on that recently. Don't hesitate to help!

Comment 38

[Greg Tatum [:gregtatum]]

Agreed but fixing tones of the warning isn't fun for anyone

Yeah, sorry if I was sounding pushy there. Thanks for helping with this. I'm super happy we have these in-tree docs. I was mostly trying to give feedback "as a new user".

Comment 39

[BugBot [:suhaib / :marco/ :calixte]]

The leave-open keyword is there and there is no activity for 6 months.
:Sylvestre, maybe it's time to close this bug?

Comment 40

[Sylvestre Ledru [:Sylvestre]]

yes autonag, we still need to work on that

Comment 41

[Surajeet Das]

<dd>If true, a multi-element search selector is used and a sequence
of elements will be returned. Otherwise a single element.

What sort of indentation is correct for these tags in the comment blocks ? @Sylvestre

Comment 42

[Sylvestre Ledru [:Sylvestre]]

dunno what you are talking about, sorry

Comment 43

[Surajeet Das]

driver.js:GeckoDriver(94):1611: (ERROR/3) Unexpected indentation.

Can you help me by telling what '94' and '1611' indicate here in this warning ?

Comment 44

[Sylvestre Ledru [:Sylvestre]]

figuring this out by yourself is part of the exercises ;)
but I would not start with the js warnings as it is more complex

Comment 45

[Surajeet Das]

Can this be assigned to me ?

Comment 46

[Sylvestre Ledru [:Sylvestre]]

I created a new bug for you. bug 1714788

Comment 47

[BugBot [:suhaib / :marco/ :calixte]]

The leave-open keyword is there and there is no activity for 6 months.
:Sylvestre, maybe it's time to close this bug?

Comment 48

[Sylvestre Ledru [:Sylvestre]]

Ouhlala, we still have about 1000 warnings...

Comment 49

[Sylvestre Ledru [:Sylvestre]]

Let's close this bug and use bug 1749473 as a meta bug for the next steps