doc: make doctool support guides

[Qard]

DO NOT MERGE

This is in-progress work to generate guide html files using the existing doctool. It's not at all ready to merge yet. I just want to get @nodejs/documentation eyes on it to decide if this seems like a valid approach.

[eljefedelrodeodeljefe]

Looks good.

Just a general thing and off slightly off topic: does this(and the rest of the js native generation) have to live in the makefile? I know it's the way it is, but if tooling increases can we think about some js build pipeline? ditch this. Probably too big of a discussion since it's a too big change and your probably need to use make vars.

[chrisdickinson]

@eljefedelrodeodeljefe There's some discussion on this going on in the Docs WG slack right now if you'd like to weigh in — the question being "should the doctool continue to consume one file at a time, producing one output file at a time, or should we move to the doctool consuming the entire directory and outputting the entire directory?"

[chrisdickinson]

cc'ing @wooorm on this with a question: as we progress with the work of using remark to render both guide documentation and API documentation in the Node repo, do you have an opinion as to whether it would be less friction to work with remark's programmatic API, or its CLI?

[wooorm]

As this is a partially done PR, I cannot advise correctly without knowing where it’s headed. Is there some document which describes where this PR is going?

For your question, I’d suggest wrapping your code as a remark plugin, then running remark’s CLI and using said plugin. As an example, I recently included natural language validation in remark (the project) as an internal remark plugin. Something like that plugin might be a good set-up?!

[kahwee]

@Qard, did you miss out doc/guide-template.html?

[Qard]

Uh...yes. It's basically just a copy/paste of the template used for api docs though. We'll need a proper html file at some point. This is all still very much in-progress. Hopefully I'll get some more time to work on it later this week. Going to see if I can adapt the tool some more to run on the entire project at once rather than file-by-file.

[jasnell]

@Qard ... what's the status on this?

[Qard]

#5408 should supersede this. Closing.