test-make-doc now failing locally

[mcollina]

• Version: master
• Platform: mac
• Subsystem: doc, test

I just pulled and test-make-doc is now failing:

$ out/Release/node /Users/matteo/Repositories/node/test/doctool/test-make-doc.js
assert.js:248
    throw err;
    ^

AssertionError [ERR_ASSERTION]: all.html is empty
    at Object.<anonymous> (/Users/matteo/Repositories/node/test/doctool/test-make-doc.js:47:10)
    at Module._compile (internal/modules/cjs/loader.js:678:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:689:10)
    at Module.load (internal/modules/cjs/loader.js:589:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:528:12)
    at Function.Module._load (internal/modules/cjs/loader.js:520:3)
    at Function.Module.runMain (internal/modules/cjs/loader.js:719:10)
    at startup (internal/bootstrap/node.js:225:19)
    at bootstrapNodeJSCore (internal/bootstrap/node.js:572:3)

This as been introduced in #19581. Not sure what I should do to make this pass again on my machine, I already tried make clean and make doc.

[mcollina]

cc @vsemozhetbyt

[vsemozhetbyt]

Throwing assertion.

Cause of the added check:

Makefile generates docs by getting the console.log() output from the tools/doc/generate.js and redirecting it to the doc files. If tools/doc/generate.js throws, an empty doc file is still created. So we can have a situation when the last .md source has an error and all the needed files are nevertheless present, just one of them is empty. So we need to check if all the files are not empty.

1. Can you check if there is an empty all.html file in out/doc/api folder?
2. Can you check if building of all.html is not broken during the process?

[vsemozhetbyt]

Can there also be some race condition? Can doctool/test-make-doc.js run till doc building is finished?

[mcollina]

Can you check if there is an empty all.html file in out/doc/api folder?

Yes it is empty,.

Can you check if building of all.html is not broken during the process?

how?

Can there also be some race condition?

This fails even if I run this individually, after make doc has finished. There shouldn't be race conditions.

Can doctool/test-make-doc.js run till doc building is finished?

I do not understand. can you rephrase?

[vsemozhetbyt]

how?

Maybe run make doc-only after deleted out/doc/api folder and check the output on console? There should be lines concerning all the doc files. (~102)

Can doctool/test-make-doc.js run till doc building is finished?

It seems this is not possible if you "run this individually, after make doc has finished." I thought there may be parallel processes of doc building and tests,

[mcollina]

Maybe run make doc-only after deleted out/doc/api folder and check the output on console? There should be lines concerning all the doc files. (~102)

That did the trick. I think we should have make clean remove this folder as well.

[lpinca]

make distclean already deletes the whole out folder.

[mcollina]

Following the principle of least surprise, a developer expects make clean to restore the tree in a state that would have “make test” pass.

[vsemozhetbyt]

Is there a way to make make rebuild a doc if it is empty?

[joyeecheung]

Following the principle of least surprise, a developer expects make clean to restore the tree in a state that would have “make test” pass.

+1. Anyone knows why make clean does not just wipe the out folder? cc @nodejs/build