cli: generate man-page

[RedYetiDev]

This PR adds a tool to generate the node.1 file. See nodejs/api-docs-tooling#125

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.41%. Comparing base (7b5d660) to head (3b55d91).

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #55268      +/-   ##
==========================================
- Coverage   88.41%   88.41%   -0.01%     
==========================================
  Files         653      653              
  Lines      187476   187476              
  Branches    36083    36090       +7     
==========================================
- Hits       165763   165761       -2     
- Misses      14946    14953       +7     
+ Partials     6767     6762       -5     

see 16 files with indirect coverage changes

[ovflowd]

Can you attach comparison of the result before and after?

[ovflowd]

There are a lot of string manipulation operations happening here, and a lot of regular expressions.

It'd be great if you extracted those regex into constants and explained them and added more inline docs regarding the string operations you're doing and why (+ attaching relevant docs to the manfile spec that are relevant for the changes here)

I even wonder if this should live here? I have the feeling this could live under the api-docs-tooling as this is certainly an API documentation but for the CLI aspect of Node.

And since a the api-docs-tooling already has a lot of builtin pieces for manipulating and parsing the Markdown and generating things, maybe it'd be a good addition there, but that's a nit.

[ovflowd]

What makes this PR hard to review are the unknowns and little documentation, which in the end creates a "trust me, bro" sentiment since (at least I, as a reviewer) was given very little to be able to review these changes. It lacks more context and references to what is relevant for me to verify that it is working as expected.

+ It'd be great to have unit testing of the individual domain logic pieces of your tooling (extract them from the main function, into separate smaller functions, which allow us to better understand their in-and-outs)

I'd also love some JSDoc here, that would also be very helpful :)

[RedYetiDev]

Thanks for the detailed review!

I hadn't even thought of it before, but I think you're right that api-docs-tooling is a nice home for this, because as you said: all the processors are already there. I'm gonna work on implementing this there, so all these string manipulations won't need to happen as much. If that's cleaner, I'll move all of this there.

What makes this PR hard to review are the unknowns and little documentation, which in the end creates a "trust me, bro" sentiment since (at least I, as a reviewer) was given very little to be able to review these changes. It lacks more context and references to what is relevant for me to verify that it is working as expected.

Yes, I should add documentation...

---

Moving to draft until:
(A) Compared with a api-docs-tooling implemention
(B) JSDoc / Docs added
(C) Reduce the unknown variables

[ovflowd]

Appreciate you!

[RedYetiDev]

Ditto back to you :-)

[RedYetiDev]

See nodejs/api-docs-tooling#125, which implements this using the already established parsers, allowing for more details (more than 1 sentence) for the mandoc. Leaving this as a draft in case that is a no-go.

[RedYetiDev]

Review note: While this removes the testing for the man page content, I have a followup PR which will revamp this test file to include it.

I chose not to include it in this PR as it changes this file drastically, and requires changes to the CLI.md file, unrelated to this change.

[ovflowd]

LGTM! Awesome stuff ✨

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/63242/

[RedYetiDev]

I'm concerned that contributors may forget to regenerate this file when they modify the CLI file, so I'll add a network test (network to download api-docs-tooling) to ensure it's properly generated.