1614820 - Editing some doc pages doesn't re-render

Status: RESOLVED FIXED

(Developer Infrastructure :: Source Documentation, defect, P1)

Description

[Michael Cooper [:mythmon]]

STR

1. Run ./mach doc, allow it to finish and open a browser
2. Navigate to http://localhost:5500/toolkit/components/normandy/normandy/execution-model.html
3. Edit toolkit/components/normandy/docs/execution-model.rst (the file that generates that page). For example, I added "Hello World" to the end of the file.

Expected

The changes should trigger a re-render and refresh the browser with the new content.

Actual

• The browser refreshes, but the new content is not there.
• The following error is printed in the console

Running Sphinx v2.2.2
Reading Sphinx metadata from build configuration
Staging static documentation
('toolkit/components/normandy/normandy/index',)

Exception occurred:
  File "/home/mythmon/src/mozilla-unified/tools/moztreedocs/__init__.py", line 207, in _synchronize_docs
    raise Exception("Uncategorized documentation. Please add it in docs/config.yml")
Exception: Uncategorized documentation. Please add it in docs/config.yml
The full traceback has been saved in /tmp/sphinx-err-sqr5_gl1.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

Note that the error does not appear to be present in the original run of Sphinx.

Notes

This does not seem to happen for all paths. For example, tools/moztreedocs/docs/jsdoc-support.rst works fine.

Stopping ./mach doc and running it again causes the new content in the modified file to be included as normal.

I tried adding toolkit/components/normandy/normandy/index to docs/config.yml in several ways, none of which seemed to work.

diff --git a/docs/config.yml b/docs/config.yml
--- a/docs/config.yml
+++ b/docs/config.yml
@@ -19,6 +19,10 @@ categories:
         - services/common/services
         - uriloader
         - code-quality
+        - toolkit/components/normandy
+        - toolkit/components/normandy/index
+        - toolkit/components/normandy/normandy
+        - toolkit/components/normandy/normandy
     build_doc:
         - mach
         - tools/try

Comment 1

[Sylvestre Ledru [:Sylvestre]]

Shivam, does it ring a bell?
P1 because this is making live of developers a pain.
I would understand that they won't touch the doc anymore after hitting this kind of issue.

Comment 2

[OOO until Jun 29 - Dan Mosedale (:dmosedale, :dmose)]

I see this same error with partial builds (eg ./mach doc browser/components/newtab/content-src/asrouter/docs). I've mostly given up on both watching and partial builds and just do a full doc build everytime and switch my attention to something else while waiting on it. I would totally expect this sort of thing to cause developers to write fewer docs.

Comment 3

[Anurag Aggarwal]

This issue is indeed because of the missing configuration of docs/config.yml
Adding - toolkit/components/normandy/normandy in the configuration resolves error at my end.
:dmose Can you please point out some files where you got the same error? I would like to test adding configuration is the best way or not.

Comment 4

[Anurag Aggarwal]

Attachment: Bug 1614820 - Fixed normandy docs not re rendering.r?#firefox-source-docs-reviewers

Comment 5

[Mark Banner (:standard8)]

The list in docs/config.yml is the top-level list for the left-hand pane of the docs site, we don't want to list absolutely everything in there, adding more documents seems to be the wrong fix.

Thinking about this some more, I think this was most likely caused by bug 1593084, that added the error message we see above.

I've just realised that the reason this is triggered is probably due to bug 1557020. When we do a rebuild, we aren't correctly rebuilding the full document tree, as a result, we only rebuild the page that has been changed. That's probably then enough to upset the index generator into thinking the page isn't part of the index (as it is no longer referenced within the index tree).

I'm not quite sure the best way forward here, maybe Andrew or Sylvestre have some ideas.

Comment 6

[Andrew Halberstadt [:ahal]]

Yeah, as I stated in bug 1557020 I was unable to get the doc re-generation working properly. I don't remember exactly what the issues were anymore, but I do remember spending way longer than I should have trying to solve it. Remember that in livereload mode we need to only rebuild the doc tree that was modified.

So unless someone is willing to dive in and fix bug 1557020, I think the most reasonable course of action here is to modify/remove the check from bug 1593084 when we are in livereload mode.

p.s I don't think Shivam had anything to do with any of this.

Comment 7

[OOO until Jun 29 - Dan Mosedale (:dmosedale, :dmose)]

(In reply to Andrew Halberstadt [:ahal] from comment #6)

So unless someone is willing to dive in and fix bug 1557020, I think the most reasonable course of action here is to modify/remove the check from bug 1593084 when we are in livereload mode.

And also when a path is passed into mach doc, which also triggers these sorts of errors?

Comment 8

[Andrew Halberstadt [:ahal]]

Yeah, iirc the livereload code essentially calls mach doc <path>, so fixing the latter should fix the former. Good clarification.

Comment 9

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/91010d49386e
Fixed normandy docs not re rendering.r=sylvestre,ahal

Comment 10

[Cristina Coroiu [:ccoroiu]]

https://hg.mozilla.org/mozilla-central/rev/91010d49386e