feat: generate API as TypeDoc docs

[huwshimi]

Status

READY

Description

Generate docs from the output using TypeDoc.

Fixes: #773.

Related PRs

List related PRs against other branches:

branch	PR
other_pr_production	link
other_pr_master	link

Todos

• Tests
• Documentation
• Changelog Entry (unreleased)

Steps to Test or Reproduce

Outline the steps to test or reproduce the PR here.

> git pull --prune
> git checkout <branch>
> grunt jasmine

1. Open the orval.config.ts for an example and add docs: true, to the output object.
2. Run yarn generate-api.
3. The markdown docs should get built alongside the API files.

[melloware]

Slick!

[soartec-lab]

sounds good! I'll try this later.

[soartec-lab]

@huwshimi

This is amazing. I have made some comments for improvement, so please check them out 👍

[soartec-lab]

I thought that the default specified location should be docs regardless of workspace or target.

These options are not documents, but output destinations for the application's HTTP client, so their nature is different from the document we will be adding this time.
Also, by not supporting those followers, we get the simplicity of the source code.

Suggested change

	let out = 'docs';
	if (app.options.isSet('out')) {
	// Use the output location if it has been set in the external config.
	out = app.options.getValue('out');
	} else if (output.workspace) {
	// Generate the docs in the workspace.
	out = upath.join(output.workspace, 'docs');
	} else if (output.target) {
	const base = upath.dirname(output.target);
	// Generate the docs along side the output target.
	out = upath.join(base, 'docs');
	}
	const out = app.options.getValue('out') || 'docs';

[huwshimi]

Thanks. app.options.getValue('out') defaults to docs inside TypeDoc so we can simplify this slightly further and drop the || 'docs'

[soartec-lab]

@huwshimi
The test has failed due to the release of v7.3.0. Can I rebase it?
I'll do this as soon as I can see that.

[huwshimi]

@soartec-lab I rebased and fixed the merge conflict. Tests are passing now.

[soartec-lab]

It's all good, Thanks!