Docs: Fix Sphinx build warnings and treat warnings as errors

[Growl1234]

Closes #7915.

Still missing:

• Four documents that are not included in any toctree (Docs: Handle sphinx build warnings and treat warnings as error #7915 (comment))
• JSON and XML syntax issues (Docs: Handle sphinx build warnings and treat warnings as error #7915 (comment) and Docs: Handle sphinx build warnings and treat warnings as error #7915 (comment))

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Growl1234]

@mohanchen Please check it when convenient, thanks!

[mohanchen]

@mohanchen Please check it when convenient, thanks!

Hi there, CUDA tests failed.

[Growl1234]

Please re-trigger it. I believe it's false-positive here, or at least unrelated to this PR.

Update: Oh there's merge conflict now, can wait for me rebasing.

[ZhouXY-PKU]

Why delete these comments?

[Growl1234]

See #7915 (comment); these comments have caused Sphinx syntax warnings.

[ZhouXY-PKU]

Just change format json to text'?

[Growl1234]

I'm not sure if you really want to change the "format"; on the one hand the highlight will disappear, on the other hand the json code would still cannot be directly copied to use anyways as json does not support commenting syntax.

@mohanchen What is your opinion? I asked about this in #7915 (comment) but didn't get reply.

[mohanchen]

The main reason we touch code is the users. So when you ask whether this line should stay or go, honestly, I'm not a mind-reader — I can't give you a definitive answer. What I do care about is that a change makes life easier for the people who actually use this code, rather than merely tidying things up for whoever wrote it.

As for this particular dpgen line: I haven't seen anyone actually use it or report any feedback on it. If you want to delete it, I have no reason to stop you, and I'm fine with that.

All I'd ask is this — if one day a user runs into a problem with this code, please make sure you're in a position to help that person out. That's it.

[Growl1234]

In case you didn't see it, for relevant notes here I've already put as an "important" box below. So hopefully this keeps the negative impact to a minimum. If feedback shows that many users are genuinely unhappy with it, we can add it to the suppression list - maybe at the cost of potentially hiding relevant errors. Still, with comments JSON code is not valid and cannot be directly used.