Skip to content

Commit 206e4f8

Browse files
griest024griest024
authored
feat(dgeni,daffio): move docs rendering to daffio (#3550)
1 parent aa764bb commit 206e4f8

47 files changed

Lines changed: 891 additions & 507 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/daffio/src/app/docs/api/api.module.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import { DaffioDocsApiRoutingModule } from './api-routing.module';
88
import { provideDaffioDocsApiContentComponent } from './components/api-content/api-content.provider';
99
import { DaffioApiListModule } from './components/api-list/api-list.module';
1010
import { DaffioApiListPageComponent } from './pages/api-list-page/api-list-page.component';
11+
import { daffioDocsApiRolesProvider } from './roles/api-roles.provider';
1112

1213
@NgModule({
1314
imports: [
@@ -26,6 +27,7 @@ import { DaffioApiListPageComponent } from './pages/api-list-page/api-list-page.
2627
],
2728
providers: [
2829
provideDaffioDocsApiContentComponent(),
30+
...daffioDocsApiRolesProvider(),
2931
],
3032
})
3133
export class DaffioApiModule {}

‎apps/daffio/src/app/docs/api/components/api-content/api-content.component.html‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,6 @@
22
@if (isApiPackage()) {
33
<daffio-api-package [doc]="doc()"></daffio-api-package>
44
} @else {
5-
<div [innerHTML]="doc().contents | safe"></div>
6-
@if (doc().examples.length > 0) {
7-
<h2 id="examples">Examples</h2>
8-
}
9-
@for (example of doc().examples; track example.id) {
10-
<h3 [attr.id]="example.id">{{example.caption}}</h3>
11-
<div [innerHTML]="example.body | safe"></div>
12-
}
5+
<ng-template [ngComponentOutlet]="component()" [ngComponentOutletInputs]="{doc: doc()}"></ng-template>
136
}
147
</daffio-doc-viewer>

‎apps/daffio/src/app/docs/api/components/api-content/api-content.component.ts‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { NgComponentOutlet } from '@angular/common';
12
import {
23
Component,
34
ChangeDetectionStrategy,
@@ -10,9 +11,9 @@ import {
1011
DaffDocKind,
1112
} from '@daffodil/docs-utils';
1213

13-
import { DaffioSafeHtmlPipe } from '../../../../core/html-sanitizer/safe.pipe';
1414
import { DaffioDocViewerComponent } from '../../../components/doc-viewer/doc-viewer.component';
1515
import { DaffioDocsDynamicContent } from '../../../dynamic-content/dynamic-content.type';
16+
import { DaffioDocsApiDynamicContentComponentService } from '../../dynamic-content/dynamic-content-component.service';
1617
import { DaffioApiPackageComponent } from '../api-package/api-package.component';
1718

1819
@Component({
@@ -22,7 +23,7 @@ import { DaffioApiPackageComponent } from '../api-package/api-package.component'
2223
imports: [
2324
DaffioDocViewerComponent,
2425
DaffioApiPackageComponent,
25-
DaffioSafeHtmlPipe,
26+
NgComponentOutlet,
2627
],
2728
})
2829
export class DaffioDocsApiContentComponent implements DaffioDocsDynamicContent<DaffApiDoc> {
@@ -31,4 +32,9 @@ export class DaffioDocsApiContentComponent implements DaffioDocsDynamicContent<D
3132
readonly isApiPackage = computed(() => this.doc().docType === 'package');
3233

3334
doc = input<DaffApiDoc>();
35+
component = computed(() => this.componentService.getComponent(this.doc()));
36+
37+
constructor(
38+
private componentService: DaffioDocsApiDynamicContentComponentService,
39+
) {}
3440
}

‎apps/daffio/src/app/docs/api/components/api-package/api-package.component.html‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
<div class="daffio-api-package__wrapper">
22
<div class="daffio-api-package__header">
3-
<h1 class="daffio-api-package__package-name">{{doc.title}}</h1>
4-
@if (doc.description) {
5-
<p class="daffio-api-package__package-description">{{doc.description}}</p>
3+
<h1 class="daffio-api-package__package-name">{{doc().title}}</h1>
4+
@if (doc().description) {
5+
<p class="daffio-api-package__package-description">{{doc().description}}</p>
66
}
77
</div>
8-
<daffio-api-list-section [children]="doc.children | apiPackageFilter:true"></daffio-api-list-section>
8+
<daffio-api-list-section [children]="doc().children | apiPackageFilter:true"></daffio-api-list-section>
99
</div>
1010

11-
@for (package of doc.children | apiPackageFilter; track package.id) {
11+
@for (package of doc().children | apiPackageFilter; track package.id) {
1212
<div class="daffio-api-package__wrapper">
1313
<h2 class="daffio-api-package__subpackage-name">
1414
<a [routerLink]="package.path">{{package.title}}</a>

‎apps/daffio/src/app/docs/api/components/api-package/api-package.component.spec.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ describe('DaffioApiPackageComponent', () => {
100100
});
101101

102102
it('should be able to take doc as input', () => {
103-
expect(component.doc).toEqual(wrapper.apiListValue);
103+
expect(component.doc()).toEqual(wrapper.apiListValue);
104104
});
105105

106106
describe('for every subpackage in children', () => {

‎apps/daffio/src/app/docs/api/components/api-package/api-package.component.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
import {
22
Component,
3-
Input,
43
ChangeDetectionStrategy,
54
HostBinding,
5+
input,
66
} from '@angular/core';
77
import { RouterLink } from '@angular/router';
88

@@ -34,5 +34,5 @@ export class DaffioApiPackageComponent {
3434
/**
3535
* A list of references for API documents.
3636
*/
37-
@Input() doc: DaffApiPackageDoc;
37+
doc = input<DaffApiPackageDoc>();
3838
}

‎apps/daffio/src/app/docs/design/design.module.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { NgModule } from '@angular/core';
33
import { provideDaffioDocsDesignComponentContentComponent } from './components/component-content/component-content.provider';
44
import { DaffioDocsDesignRoutingModule } from './design-routing.module';
55
import { DaffioDocsDesignIndexService } from './services/index.service';
6+
import { daffioDocsApiRolesProvider } from '../api/roles/api-roles.provider';
67
import { provideDaffioDocsPackagesContentComponent } from '../packages/components/packages-content/packages-content.provider';
78

89
@NgModule({
@@ -13,6 +14,7 @@ import { provideDaffioDocsPackagesContentComponent } from '../packages/component
1314
DaffioDocsDesignIndexService,
1415
provideDaffioDocsDesignComponentContentComponent(),
1516
provideDaffioDocsPackagesContentComponent(),
17+
...daffioDocsApiRolesProvider(),
1618
],
1719
})
1820
export class DaffioDocsDesignModule {}

‎tools/dgeni/build.ts‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import {
1212
explanationDocsPackage,
1313
designDocsPackage,
1414
} from './src/transforms/daffodil-guides-package';
15+
import { daffodilRoutesPackage } from './src/transforms/daffodil-routes-package';
1516

1617
rimraf('../../dist/docs/*', { glob: true }).then(() => {
1718
new Dgeni([apiDocs]).generate().then(() => {
@@ -34,13 +35,18 @@ rimraf('../../dist/docs/*', { glob: true }).then(() => {
3435
// run them after base docs so that config between shared processors does not conflict
3536
// a design flaw of dgeni, it wasn't meant to be run in parallel
3637
new Dgeni([designApiPackage]).generate().then(() => {
37-
new Dgeni([designDocsPackage]).generate().catch((err) => {
38+
Promise.all([new Dgeni([designDocsPackage]).generate().catch((err) => {
3839
console.log(err);
3940
process.exit(1);
40-
});
41+
}),
4142
new Dgeni([designExamplePackage]).generate().catch((err) => {
4243
console.log(err);
4344
process.exit(1);
45+
})]).then(() => {
46+
new Dgeni([daffodilRoutesPackage]).generate().catch((err) => {
47+
console.log(err);
48+
process.exit(1);
49+
});
4450
});
4551
}).catch((err) => {
4652
console.log(err);

‎tools/dgeni/src/processors/add-api-symbols-to-package.ts‎

Lines changed: 21 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
import { Document } from 'dgeni';
22
import { slugify } from 'markdown-toc';
3-
import type { Environment } from 'nunjucks';
43

54
import {
65
DaffApiDoc,
6+
daffDocsApiArrayToDict,
7+
DaffDocsApiRole,
8+
daffDocsApiRoleGetSectionLabel,
9+
daffDocsApiRoleSort,
710
DaffDocTableOfContents,
811
} from '@daffodil/docs-utils';
912

1013
import { CollectLinkableSymbolsProcessor } from './collect-linkable-symbols';
11-
import { API_TEMPLATES_PATH } from '../transforms/config';
1214
import { FilterableProcessor } from '../utils/filterable-processor.type';
1315

1416
export const ADD_API_SYMBOLS_TO_PACKAGES_PROCESSOR_NAME = 'addApiSymbolsToPackages';
1517

16-
const LINK_TAG = /\{@link (\w+)}/g;
17-
1818
export class AddApiSymbolsToPackagesProcessor implements FilterableProcessor {
1919
readonly name = ADD_API_SYMBOLS_TO_PACKAGES_PROCESSOR_NAME;
2020
readonly $runAfter = ['paths-absolutified'];
@@ -23,56 +23,35 @@ export class AddApiSymbolsToPackagesProcessor implements FilterableProcessor {
2323
docTypes = [];
2424
lookup = (doc: Document) => doc.id;
2525

26-
constructor(
27-
private templateEngine,
28-
private templateFinder,
29-
) {}
30-
3126
$process(docs: Array<Document>): Array<Document> {
32-
const templates = this.templateFinder.templateFolders;
33-
this.templateFinder.templateFolders = [
34-
API_TEMPLATES_PATH,
35-
...templates,
36-
];
37-
const render: Environment['render'] = this.templateEngine.getRenderer();
38-
3927
const ret = docs.map(doc => {
4028
if (this.docTypes.includes(doc.docType)) {
4129
const exportDocs = CollectLinkableSymbolsProcessor.packages.get(this.lookup(doc));
42-
doc.symbols = exportDocs?.map((d) => d.slug);
43-
// the inline tag processor runs after doc rendering and
44-
// doesn't expose anything besides `$process` so trick it into processing our child docs
45-
doc.api = exportDocs?.map((symbol) =>
46-
render(
47-
this.templateFinder.getFinder()(symbol),
48-
{ doc: symbol, child: true },
49-
).replaceAll(
50-
LINK_TAG,
51-
(match, linkableSymbol) => `<a href="${CollectLinkableSymbolsProcessor.symbols.get(linkableSymbol)}"><code>${linkableSymbol}</code></a>`,
52-
),
53-
);
54-
doc.apiToc = exportDocs?.flatMap((symbol: Document & DaffApiDoc): DaffDocTableOfContents => [
55-
{
56-
content: symbol.name,
57-
lvl: 2,
58-
slug: slugify(symbol.name),
59-
},
60-
// ...symbol.tableOfContents.map((entry) => ({
61-
// ...entry,
62-
// lvl: entry.lvl + 1,
63-
// slug: entry.slug === 'examples' ? `${symbol.slug}-examples` : entry.slug,
64-
// })),
65-
]);
30+
if (exportDocs) {
31+
doc.symbols = exportDocs?.map((d) => CollectLinkableSymbolsProcessor.symbols.get(d.name));
32+
const api = daffDocsApiArrayToDict(exportDocs);
33+
doc.apiToc = daffDocsApiRoleSort(<Array<DaffDocsApiRole>>Object.keys(api))?.flatMap((role): DaffDocTableOfContents => [
34+
{
35+
content: daffDocsApiRoleGetSectionLabel(role),
36+
lvl: 2,
37+
slug: role,
38+
},
39+
...api[role].map((apiDoc: Document & DaffApiDoc) => ({
40+
content: apiDoc.name,
41+
lvl: 3,
42+
slug: slugify(apiDoc.name),
43+
})),
44+
]);
45+
}
6646
}
6747
return doc;
6848
});
6949

70-
this.templateFinder.templateFolders = templates;
7150
return ret;
7251
}
7352
};
7453

7554
export const ADD_API_SYMBOLS_TO_PACKAGES_PROCESSOR_PROVIDER = <const>[
7655
ADD_API_SYMBOLS_TO_PACKAGES_PROCESSOR_NAME,
77-
(templateEngine, templateFinder) => new AddApiSymbolsToPackagesProcessor(templateEngine, templateFinder),
56+
() => new AddApiSymbolsToPackagesProcessor(),
7857
];

‎tools/dgeni/src/processors/addInheritedDocsContent.spec.ts‎

Lines changed: 0 additions & 62 deletions
This file was deleted.

0 commit comments

Comments
 (0)