feat: Re-Add the docs command

[maschad]

Re-introducing the docs command to generate Docs for a project and publish them to gh pages

Closes #1105

[achingbrain]

@maschad I hope you don't mind but I just pushed a couple of commits to get this working.

I think to land it we need to sort out the following:

• Choose a nice theme that's readable
• Work out how to handle monorepos without extra user config (e.g. https://github.com/libp2p/js-libp2p-peer-id)
  • the isMonorepoProject variable exported from src/utils.js will tell you if the current project is a monorepo
  • tscdoc has a "packages" strategy for monorepos but I couldn't get it to work
• Entry points/What to document
  • it should read these out of tsconfig.json but I couldn't get it to work either
  • I hardcoded src/* as the entry point - it's the convention for aegir-managed projects but maybe we don't want that
  • At the moment it creates jsdocs for everything, including internal classes/functions which is pretty overwhelming
  • Do we want this?
  • Would it be better to instead parse the exports map out of a project's package.json and only generate docs for those files?
• Update the check-project command to add a docs link pointing to the gh-pages site for the project to the README

[maschad]

@maschad I hope you don't mind but I just pushed a couple of commits to get this working.

No problem @achingbrain any help is always appreciated!

it should read these out of tsconfig.json but I couldn't get it to work either

This had actually been my stumbling block last few days, I will continue to dig into it.

Choose a nice theme that's readable

Is there any particular criteria that you would want to consider for readability? Because I was thinking we could continue with the default theme. It may also be worth considering a Github Wiki compatible theme in case repos don't want to host using gh-pages.

tscdoc has a "packages" strategy for monorepos but I couldn't get it to work

I'll take a look.

I hardcoded src/* as the entry point - it's the convention for aegir-managed projects but maybe we don't want that

Agreed, fixing the issue mentioned above should solve this.

Do we want this?

I am assuming you are referring to ....

At the moment it creates jsdocs for everything, including internal classes/functions which is pretty overwhelming

.... I would say no, the impetus to add this feature was around documentation for configuration, so I would say it should exclude internal functions/classes.

Would it be better to instead parse the exports map out of a project's package.json and only generate docs for those files?

I think this is a good idea, I can't see an immediate use for generating docs for a module
not listed in exports since importing it would lead to a ModuleNotFound Error

Update the check-project command to add a docs link pointing to the gh-pages site for the project to the README

Good point! Will do.

[maschad]

Following up on this:

I think this is a good idea, I can't see an immediate use for generating docs for a module
not listed in exports since importing it would lead to a ModuleNotFound Error

I adjusted the entryPoint to default to the exports map of a project's package.json and created this issue for monorepos and this for parsing the tsconfig.json for entryPoints.

Once I confirm it works I will open the PR for review.

[github-actions]

🎉 This PR is included in version 37.6.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀