feat(dgeni): render API source block

[griest024]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/graycoreio/daffodil/blob/develop/CONTRIBUTING.md#commit
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Documentation content changes
[ ] Other... Please describe:

What is the current behavior?

Fixes: #3306

What is the new behavior?

One of the major outstanding issues with this is that the dgeni TS package doesn't correctly infer types of everything that TS can. For example, injection tokens and providers that are destructured from the factory function are untyped. Functions that do not have explicit return annotations have untyped return types even when TS correctly infers the return type.

Some of the consts that are function do have some of their type correctly inferred though.

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

[griest024]

@xelaint @damienwebdev this is ready to preview and give feedback

[xelaint]

Is it possible to make the individual properties within the source block linkable to the properties section? When a user is on a page with a long source block section (i.e. /docs/api/cart/state/DaffCartFacade), the individual properties take a while to scroll to.

[xelaint]

I don't think it's necessary to have this heading?

[griest024]

While I'm not attached to this specific heading, I think some separator between the description and the source block is necessary. When the descriptions includes some code blocks at the end (which is fairly common), I think its not immediately apparent that the source block is not part of the description. See /docs/api/auth/state/daffAuthProvideUnauthenticatedHooks:

[xelaint]

Yeah, I agree there should be a separator then. Is the providers code block a usage example? If so, I think we should also label it as usage example as well, or split up usage example and api into tabs like how angular does it?

[griest024]

yes the provider block is a usage example. I agree, we should tag it as @example and render it separately (tabs sound good)

[xelaint]

yes the provider block is a usage example. I agree, we should tag it as @example and render it separately (tabs sound good)

Sounds good. @damienwebdev likes the idea of tabs as well.

[griest024]

Is it possible to make the individual properties within the source block linkable to the properties section? When a user is on a page with a long source block section (i.e. /docs/api/cart/state/DaffCartFacade), the individual properties take a while to scroll to.

yes this is my eventual goal. I'm not sure if it should be in this PR though since it will require changes to how the properties are laid out

[xelaint]

Do we need to render the API blocks for design?

[griest024]

Do we need to render the API blocks for design?

I like them but I'll leave the final decision up to you and @damienwebdev. I have them here mostly as an example of what the source blocks will look like for components.