Is this a regression?

Yes

Description

Default values for method parameters are displayed as [object Object] in the API page presentation.
The signature for this method is:

  enable(id: string, enabled = true)

Please provide the exception or error you saw

No response

OS

Unix (Linux, macOS, etc.)

Browser

Chrome

Node version

18.12.1

Anything else?

No response

Is this a regression?

Yes

Description

Not rebuild a page automatically
I creating the page and create the documentation page
if i was edit the page, page don't reloading an me need restart the dev server by stopping batch job and run ng serve again
and ng g @ng-doc/builder:standalone-pages-migration doesn't work

Please provide the exception or error you saw

No response

OS

Windows

Browser

Other

Node version

latest

Anything else?

No response

Description

Any project sometimes requires changes that lead to backward incompatibility of versions. To make the update process easier for users, it is necessary to add a migration mechanism.

Proposed solution

Angular schematics can be used so that users can execute a single command ng update @ng-doc/builder for automatic updates and migrations.

This feature is quite large and requires the implementation of migrations for TypeScript, CSS, and HTML code, so it will take some time.

Alternatives considered

Description

When I add an API Entity with multiple scopes, the API List gets very long and I need to do a lot of scrolling to find the scope that I want. Setting the order property of NgDocApiScope does not change the order in the API List.

Proposed solution

When I add an API Entity that includes multiple scopes, I want to show the API List for each scope on a separate page. I want the main "API" link in the sidebar to act like a category so I can expand it to see the list of scopes and click on one of them to go to the API List for that scope.

Alternatives considered

• Put a "Scope" filter at the top of the API List next to the "Filter" and "Type" controls
• Just fix the behavior of NgDocApiScope.order

Description

NgDoc doesn't show a generic type for classes, interfaces, types, etc. so it should be convenient to see a generic type.

Proposed solution

Start displaying them as a part of the title, just need to test how it looks with long generic types.

Alternatives considered

No alternatives were considered.

Is this a regression?

Yes

Description

Reproduction:

1. Set angularBuilder: "esbuild",
2. Set cache: true,
3. Start in dev mode.
4. Change a page's markdown content.
5. ng-doc seems to recompile the page, but when the app reloads the updates aren't applied.

Please provide the exception or error you saw

No response

OS

macOS

Browser

Chrome

Node version

18.14.0

Anything else?

This is on the freshly released Angular 16.1.0, but I recall seeing this problem a week or so ago as well.

Is this a regression?

I don't know

Description

When I build my ng-doc app with ng build --base-href=/my-site/ (for publishing to GitHub Pages) or set baseHref option in angular.json and run it with ng serve, the navigation links (in both the left menu and next/prev) throw the following error. The routes work correctly if I enter the URL directly into the browser. Links that were generated from markdown display the wrong URL on hover, but work correctly when I click on them.

Please provide the exception or error you saw

core.mjs:8506 ERROR Error: Uncaught (in promise): Error: NG04002: Cannot match any routes. URL Segment: 'my-site/getting-started/installation'
Error: NG04002: Cannot match any routes. URL Segment: 'my-site/getting-started/installation'
    at ApplyRedirects.noMatchError (router.mjs:3614:16)
    at router.mjs:3596:28
    at catchError.js:10:39
    at OperatorSubscriber._error (OperatorSubscriber.js:23:21)
    at OperatorSubscriber.error (Subscriber.js:40:18)
    at OperatorSubscriber._error (Subscriber.js:64:30)
    at OperatorSubscriber.error (Subscriber.js:40:18)
    at OperatorSubscriber._error (Subscriber.js:64:30)
    at OperatorSubscriber.error (Subscriber.js:40:18)
    at OperatorSubscriber._error (Subscriber.js:64:30)
    at resolvePromise (zone.js:1211:31)
    at resolvePromise (zone.js:1165:17)
    at zone.js:1278:17
    at _ZoneDelegate.invokeTask (zone.js:406:31)
    at core.mjs:23999:55
    at AsyncStackTaggingZoneSpec.onInvokeTask (core.mjs:23999:36)
    at _ZoneDelegate.invokeTask (zone.js:405:60)
    at Object.onInvokeTask (core.mjs:24300:33)
    at _ZoneDelegate.invokeTask (zone.js:405:60)
    at Zone.runTask (zone.js:178:47)

OS

Unix (Linux, macOS, etc.)

Browser

Chrome

Node version

18.12.1

Anything else?

No response

Is this a regression?

I don't know

Description

After creating a brand new angular app and adding ng-doc I can't use the schematics to create ng-doc things.

Steps to reproduce:

1. ng new
2. npm i @angular-devkit/[email protected]
3. ng add @ng-doc/add
4. Use some ng-doc generate command like ng g @ng-doc/builder:page "Installation" or ng g @ng-doc/builder:category "Getting Started"

Please provide the exception or error you saw

The "path" argument must be of type string. Received undefined

OS

Windows

Browser

None

Node version

16.19.1

Anything else?

• ng version information is:

Angular CLI: 16.1.1
Node: 16.19.1
Package Manager: npm 9.6.7
OS: win32 x64

• follow up to #69

Description

With the release of standalone components, modules have become optional, although NgDoc still uses them, for example, to import and export dependencies for demos and playgrounds.

For Angular projects that have switched to standalone components and are ready to create standalone components for demos, it is possible to make the use of page modules optional as well, which will allow using only the ng-doc.dependencies.ts file for dependencies. This improvement should reduce the number of files and make it easier to create demos and playgrounds.

Proposed solution

To achieve this, make the module property in ng-doc.dependencies.ts optional if demo components and components used for playgrounds are standalone.

It's also necessary to add standalone property for dependencies and page schematics

Alternatives considered

Description

NgDoc displays protected members of classes, but there is nothing that says a member is protected

Proposed solution

Display protected keyword next to the member name like readonly or abstract members

Alternatives considered

nope.

Is this a regression?

I don't know

Description

Steps to reproduce

• ng new to create a new app.
• ng add @ng-doc/add as per quick start guide.

Expected

NgDoc setup to succeed.

Actual

NgDoc setup fails with the following error message:

ℹ Using package manager: npm
✔ Found compatible package version: @ng-doc/[email protected].
✔ Package information loaded.

The package @ng-doc/[email protected] will be installed and executed.
Would you like to proceed? Yes
✔ Packages successfully installed.
Cannot find module 'C:\dev\repos\temp\docs-test\node_modules@angular-devkit\core\src\virtual-fs\host.js'

Please provide the exception or error you saw

Cannot find module 'C:\dev\repos\temp\docs-test\node_modules@angular-devkit\core\src\virtual-fs\host.js'

OS

Windows

Browser

None

Node version

16.19.1

Anything else?

• tried doing npm install @angular-devkit/core and retrying the ng add @ng-doc/add command but same result.
• ng version information is:

Angular CLI: 16.1.1
Node: 16.19.1
Package Manager: npm 9.6.7
OS: win32 x64

• package.json state after ng add @ng-doc/add command failed:

"dependencies": {
"@angular-devkit/core": "^16.1.1",
"@angular/animations": "^16.1.0",
"@angular/common": "^16.1.0",
"@angular/compiler": "^16.1.0",
"@angular/core": "^16.1.0",
"@angular/forms": "^16.1.0",
"@angular/platform-browser": "^16.1.0",
"@angular/platform-browser-dynamic": "^16.1.0",
"@angular/router": "^16.1.0",
"@ng-doc/add": "^16.6.3",
"rxjs": "~7.8.0",
"tslib": "^2.3.0",
"zone.js": "~0.13.0"
},
"devDependencies": {
"@angular-devkit/build-angular": "^16.1.1",
"@angular/cli": "~16.1.1",
"@angular/compiler-cli": "^16.1.0",
"@types/jasmine": "~4.3.0",
"jasmine-core": "~4.6.0",
"karma": "~6.4.0",
"karma-chrome-launcher": "~3.2.0",
"karma-coverage": "~2.2.0",
"karma-jasmine": "~5.1.0",
"karma-jasmine-html-reporter": "~2.1.0",
"typescript": "~5.1.3"
}

Description

Based on the conversation in #23 ticket, I think it's a good idea to allow multiple API configurations, it could be useful for monorepos or for projects that would like to split the API entities into different pages

Proposed solution

Just start processing multiple API configs and creating a page for each config

Alternatives considered

Is this a regression?

Yes

Description

The application no longer starts since upgrading to version 15.7.1. It wasn't happening on 15.6.0.

Please provide the exception or error you saw

An unhandled exception occurred: require() of ES Module /Users/rbower/code/qc/qui/qui-components/node_modules/.pnpm/[email protected]/node_modules/unist-util-visit/index.js from /Users/---/node_modules/.pnpm/@[email protected]_gdu3eq3akq4hce7nemjw5rcmk4/node_modules/@ng-doc/builder/engine/post-processors/html-plugins/slugger.js not supported.
Instead change the require of index.js in /Users/---/node_modules/.pnpm/@[email protected]_gdu3eq3akq4hce7nemjw5rcmk4/node_modules/@ng-doc/builder/engine/post-processors/html-plugins/slugger.js to a dynamic import() which is available in all CommonJS modules.
See "/private/var/---/angular-errors.log" for further details.

OS

Unix (Linux, macOS, etc.)

Browser

Chrome

Node version

18.14.0

Anything else?

I see that ts-node was added as a peer dependency in 15.7.0. I installed this but still encountered the above error. Not sure what it's being used for, but I'd recommend tsx be used in its place if possible.

Is this a regression?

Yes

Description

After upgrading from 15.10.5 to 15.11.1, I see the following error

Please provide the exception or error you saw

Error: node_modules/@ng-doc/ui-kit/types/content.d.ts:8:5 - error TS2416: Property 'createInjector' in type 'NgDocComponentContent<T, C>' is not assignable to the same property in base type 'PolymorpheusComponent<T, C>'.
  Type '(injector: Injector, context: C, providers?: StaticProvider[] | undefined) => Injector' is not assignable to type '<C>(injector: Injector, useValue?: C | undefined) => Injector'.
    Types of parameters 'context' and 'useValue' are incompatible.
      Type 'C | undefined' is not assignable to type 'C'.
        'C' could be instantiated with an arbitrary type which could be unrelated to 'C | undefined'.

8     createInjector(injector: Injector, context: C, providers?: StaticProvider[]): Injector;
      ~~~~~~~~~~~~~~

OS

Unix (Linux, macOS, etc.)

Browser

Chrome

Node version

18.15.0

Anything else?

No response

Is your feature request related to a problem? Please describe.
I think it will be very useful to add the ability to use a keyword feature along with anchors to class method, class properties in API, or guideline headers.

Describe the solution you'd like
The probably expected syntax should look like this:

• MyClass.methodName, MyClass.propertyName - for API anchors, looks native and will work in code examples
• *GettingStarted#how-to-install - for guidelines, accepts the anchor as is and adds it to the URL
• in my opinion, it's not necessary for global keywords, because they may be specified via URL which should be more flexible

Description

Angular v14 introduced experimental support for esbuild, and Angular v15 improved on that support.
https://blog.angular.io/angular-v15-is-now-available-df7be7f2f4c8

Depending on how the ng-doc internals hook into the Angular build process, the esbuild option might speed up builds and watch mode. I'm not sure how much of a pain this would be to integrate.

Proposed solution

Add configuration option to enable @angular-devkit/build-angular:browser-esbuild.

Alternatives considered

None

Description

An idea has emerged to automatically gather and display changes that have occurred in a project based on changes in the repository.

If your project uses the commit format adopted by Angular, then NgDoc could automatically gather and display such changes on certain pages based on the scope.

Proposed solution

This function should be optional by default and only enabled after setup:

• There should be an option to set a scope for each guide that corresponds to the scope in the commit. Based on this scope, NgDoc will gather and display changes for each page. By default, the current guide route can be used as a scope.
• There should be an option to configure the range of versions from which changes will be gathered, for example, for the last 5 minor versions, the latest major version, etc.
• It should be possible to configure the types of commits that should be taken when displaying changes, for example, only gathering changes for the types of docs, feat, fix.
• In the sidebar, an icon "New"/"Update" must be displayed to inform the user that related scope to the guide has been created, changed or updated.
• add option to avoid adding changes to the change log, it can be [skip ng-doc] tag in the body of the commit

Issues to address before implementation:

• Should the list of changes for the API be displayed? If so, based on what criteria? One option could be to use the declaration name as a scope to match the commit change with the API page.

Alternatives considered

There is also an option to make the display of changes more flexible on any required page. For example, NgDocActions could be used to pass a list of scopes for which the list of changes needs to be rendered. In this case, it can be displayed anywhere on the page, and the issue with the API will disappear on its own because the user can decide which scopes to render for the page. However, this will add additional load on the user and require them to add such a call to every page.

Description

Super interested in this library, but it's not clear to me what kind of documentation is generated by using ng-doc. Are there any screenshots available of what the end result looks like after setting everything up?

Description

With the release of Angular 16, it is necessary to update NgDoc to version 16 by adding support for Angular 16.

Proposed solution

This task does not include any changes or improvements to the code related to new Angular features, but only involves updating packages.

Alternatives considered

Description

I want to investigate and if possible add integration with StackBlitz for demos.

NgDoc knows the demo code, which has simplified the handling of standalone components in many ways. This will also make it easier to dynamically create StackBlitz projects where users can play around with and modify the demo code.

Proposed solution

Enable the creation of a default configuration for the StackBlitz project's API, which will include all the necessary imports and package versions. If this configuration exists, automatically display a StackBlitz button for each demo in the guides. When the button is clicked, it will create and display the StackBlitz project in a new tab of the browser.

This is just an idea for now. More information will be known once I start working on it.

Alternatives considered

Description

NgDoc has several types of configuration files, such as ng-doc.page.ts, ng-doc.category.ts, and so on, which we compile to later load and generate documentation based on them.

We also have an ng-doc.dependencies.ts file which was separated from the main page configuration to save time on compilation. The thing is, ng-doc.dependencies.ts may have dependencies on components and modules which, in turn, may depend on entire libraries. To load such a configuration, we would have to compile the file with all its dependencies, which would lead to performance issues. That's why I separated the dependencies file into a separate file and simply imported it directly where necessary.

However, while working on task #12, it became clear that we couldn't do without compiling the dependencies file, as some configuration fields for the playground can be passed from the outside, for example the data field.

During various tests, I found a solution for compilation. Instead of the TypeScript compiler, I migrated the library to esbuild, which did not affect performance, while allowing us to load dependency files as a whole.

Having achieved this result, I came to the conclusion that the separate configuration file ng-doc.dependencies.ts is no longer needed, and I can transfer its configuration to the NgDocPage interface, so that users can configure everything related to the page in one file, ng-doc.page.ts, which I think will simplify the configuration.

Proposed solution

Just move the dependencies file configuration from NgDocDependencies to the NgDocPage interface, and deprecate the ng-doc.dependecies.ts file.

export interface NgDocPage {
	mdFile: string;
	title: string;
	category?: NgDocCategory;
	route?: string;
	onlyForTags?: string[];
	order?: number;
	keyword?: string;
	data?: unknown;
        // Just add it here
	module?: Type<unknown>;
	demos?: Record<string, Type<unknown>>;
	playgrounds?: Record<string, NgDocPlaygroundConfig>;
}

I will mark the use of the ng-doc.dependencies.ts file as deprecated at first, and add an additional option to specify the configuration in ng-doc.page.ts, and completely remove it with the release of version 17.0.0 which will be released with Angular 17.

Alternatives considered

Description

When I write a guide for one of my library's components, I want to include API documentation for that component's class (inputs, outputs, properties, methods, jsdoc comments) alongside the guide's markdown and demos so readers can find all relevant documentation for a component in one place (like the Angular Material docs for example). Currently, API and Guide are separate pages and I don't see any way to combine them, aside from adding a link to the corresponding API page.

Proposed solution

Maybe add methods to NgDocActions for rendering the API documentation (or pieces of the API documentation)? For example:

  NgDocActions.apiPage("MyComponent")
or
  NgDocActions.apiDescription("MyComponent")
  NgDocActions.apiConstructor("MyComponent")
  NgDocActions.apiProperties("MyComponent")
  NgDocActions.apiMethods("MyComponent")

Maybe this could be accomplished with existing functionality by doing something like

  NgDocActions.demo("NgDocPageComponent")

but I haven't figured out how to wire that up, if it's even possible.

Alternatives considered

If you are planning to do #21 maybe you could add a Guide tab on the API page that pulls its content from a page with corresponding NgDocPage.api property (or something like that). Then render that API page (including Guide tab) in place of the guide page.

Is this a regression?

I don't know

Description

I have two pages and the first page's route is a substring of the second page's route. The prevPage and nextPage links are incorrect on the second page because it is matching the route of the first page.

The generated context.navigation looks like:

		navigation: [
			{
				title: 'Components',
				route: '/components',
				expandable: true,
				expanded: true,
				children: [
			{
				title: 'Chart',
				route: '/components/chart',
			},
			{
				title: 'Chart Summary',
				route: '/components/chart-summary',
			},

Likely source location of the bug:
https://github.com/skoropadas/ng-doc/blob/ca28b10b460a52091ca5a27f7175ae50c0170397/libs/app/components/page/page.component.ts#L24-L31

Please provide the exception or error you saw

No response

OS

Unix (Linux, macOS, etc.)

Browser

Chrome

Node version

18.12.1

Anything else?

No response

Description

At the moment NgDoc supports only a few TSDoc tags, we need to expand support for tags to make it clear to users which standard we support and also add documentation on how to use them. Below is a table of tags with the current and required support

Proposed solution

Some tags are not needed (for example, @decorator), since the documentation engine collects this information from the code, but most of them are necessary in order to display warnings or sort the documentation content.

It doesn't mean that you can't use these tags, it means that they will not be covered by NgDoc and displayed in documentation on API pages.

Alternatives considered

Description

Currently, every anchor element (h1-h6) generates an anchor link.

Proposed solution

I'd like to be able to customize these levels (e.g. only generate links for h1, h2, h3 elements)

Alternatives considered

None

Description

I currently supply my own side navigation, header, breadcrumbs, and prev/forward page links.

The side nav and header are pretty easy to override, but the breadcrumbs and page links don't have the same customization. For the breadcrumbs, I force the original elements to hide using display: none css and then render my own. For the page links, I've just styled what you've provided, but I'd like to supply my own if possible.

These elements are contained within the <router-outlet>, so overriding them might be an involved process to set up.

Proposed solution

Give us an option to supply our own breadcrumbs component, much like we can already do for the sidebar and header.

Alternatives considered

Force the original elements to hide using CSS and then render my own.

Description

Hi,

Thank you for this great library, which seems to be the best alternative to Storybook (and I'm not exaggerating in my words). Everything is so simple to use, and it makes me feel so powerful... :)

I had some difficulties installing and configuring everything, and by fiddling a bit with the files, I think that the documentation should be updated (or at least, write a part on the integration in Nx)

Here are the changes I had to do:

1. Update ng-doc.config.ts

// Update the ng-doc.config.ts

import { NgDocConfiguration } from '@ng-doc/builder';

const config: NgDocConfiguration = {
  pages: 'apps/<project-name>/src',
  tsConfig: 'apps/<project-name>/tsconfig.app.json',
};

export default config;

2. Update project.json (instead of angular.json, which is not used inside a Nx project)

{
  "name": "<your-project-name>",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "projectType": "application",
  "prefix": "design-system",
  "sourceRoot": "apps/<your-project-name>/src",
  "tags": [],
  "targets": {
    "build": {
      "executor": "@ng-doc/builder:browser",
      ...
    }
  }
}

3. Standalone AppComponent

As I use mainly Standalone Component, I also updated the part concerning the AppModule and refactored it inside the AppConfig and AppComponent

// app.config.ts

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideAnimations(),
    provideSearchEngine(NgDocDefaultSearchEngine),
    provideRouter([
      ...NG_DOC_ROUTING,
      {
        path: '',
        pathMatch: 'full',
        redirectTo: '/01-welcome', // Redirect to my splashscreen at the start of the app
      },
    ]),
    ngDocContextProvider,
    {
      provide: NG_DOC_ASSETS_PATH,
      useValue: 'assets/ng-doc/ui-kit', // To retrieve icons etc...
    },
  ],
};

// app.component.ts

@Component({
  selector: 'my-doc-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss'],
  imports: [
    NgDocRootComponent,
    NgDocNavbarComponent,
    RouterOutlet,
    NgDocSidebarComponent,
  ],
  standalone: true,
})
export class AppComponent {}

That's the main changes I've made to make it work 😄

Is this a regression?

I don't know

Description

I added ng-doc to a new Angular app using ng add @ng-doc/add and then tried to build it with ng build. I got an error about js-beautify dependency. I had to manually install this dependency to resolve the error.

Please provide the exception or error you saw

./node_modules/@ng-doc/app/fesm2020/ng-doc-app-helpers-format-html.mjs:11:14-59 - Error: Module not found: Error: Can't resolve 'js-beautify/js/lib/beautify-html.js' in 'node_modules/@ng-doc/app/fesm2020'

OS

Unix (Linux, macOS, etc.)

Browser

Chrome

Node version

18.12.1

Anything else?

No response

Is this a regression?

Yes

Description

I'm upgrading to 16.3.2 from Angular 15. It's gone well so far, but I'm noticing a strange issue when building using webpack.

If I build first using webpack, the ng-doc folder isn't generated properly. It's missing all of the pages under guides. Example:

./.ng-doc/app/ng-doc.routing.ts:3:22-70 - Error: Module not found: Error: Can't resolve '.ng-doc/app/guides/installation/module' in '/Users/rbower/code/qc/qui/qui-components/packages/angular-docs/.ng-doc/app'

./.ng-doc/app/ng-doc.routing.ts:6:22-57 - Error: Module not found: Error: Can't resolve '.ng-doc/app/guides/module' in '/Users/rbower/code/qc/qui/qui-components/packages/angular-docs/.ng-doc/app'

It works when I use the esbuild builder. However, I need to use the webpack builder because tailwind + scss isn't currently supported, and my docs site uses tailwind for demos.

What's weird is that when I build using esbuild and then switch over to webpack and build, it works just fine, even if I clear the .ng-doc folder between builds.

Please provide the exception or error you saw

./.ng-doc/app/ng-doc.routing.ts:3:22-70 - Error: Module not found: Error: Can't resolve '.ng-doc/app/guides/installation/module' in '/Users/rbower/code/qc/qui/qui-components/packages/angular-docs/.ng-doc/app'

./.ng-doc/app/ng-doc.routing.ts:6:22-57 - Error: Module not found: Error: Can't resolve '.ng-doc/app/guides/module' in '/Users/rbower/code/qc/qui/qui-components/packages/angular-docs/.ng-doc/app'

### OS

Unix (Linux, macOS, etc.)

### Browser

Chrome

### Node version

18.16.0

### Anything else?

_No response_

Is this a regression?

I don't know

Description

Component demos have extra CSS styles that are not there when rendered outside of ng-doc. For example, create a demo with a <table> element and note the margin that is coming from global.css.

Please provide the exception or error you saw

N/A

OS

Unix (Linux, macOS, etc.)

Browser

Chrome

Node version

18.12.1

Anything else?

Describe the bug
The docs recommend TypeScript imports for pages as follows:

import {NgDocPage} from '@ng-doc/builder';

export const MyAwesomePage: NgDocPage = {
    title: 'MyAwesomePage',
    mdFile: './index.md',
};

export default MyAwesomePage;

The types aren't resolved as expected. Instead, my IDE detected the types from the @ng-doc/core package.

To Reproduce
Steps to reproduce the behavior:

1. Use the default installation on a blank app.
2. Try to import the TypeScript types as done in the docs.
3. Notice as the types aren't resolved properly.

Expected behavior
The types are resolved as documented.

Describe the bug
"Unknown" text is appearing in ng-doc searchbar.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://ng-doc.com/customization/themes
2. Type "getting started" in the search bar
3. See error

Expected behavior
"Unknown" shouldn't appear.

Screenshots

Description

Initially, all dependencies were separated into a separate files to avoid compiling unnecessary dependencies. The issue is that in order to generate the page correctly, NgDoc needs to compile the ng-doc.page.ts file and dynamically load its contents to read certain values and provide access to this object in the template. If the dependencies specified in the ng-doc.dependencies.ts file were located in ng-doc.page.ts, then NgDoc would have to compile all dependencies for the file to be available for loading. This could result in a slow compilation and loading process, which is why the dependencies were separated into separate file that is currently not compiled by NgDoc.

Proposed solution

A few months ago, I increased the compilation speed of page files by using esbuild within the NgDoc engine. This opens up the possibility of combining the dependency file with the main page file, while ignoring all dependencies during compilation.

As one solution, NgDoc could remove the module, demo, and playground fields from ng-doc.page.ts files in memory before compiling them. This would keep the compilation process fast while making the creation of guides more convenient, as it eliminates the need for an additional entity both within the engine and in the file system.

Alternatives considered

Describe the bug
Using the @ng-doc/builder:browser builder, ng build completes successfully but doesn't exit.

To Reproduce
Steps to reproduce the behavior:

1. Start a new angular app.
2. Follow the installation instructions for adding @ng-doc
3. Try ng build.
4. Observe as the build emits a completion message, but hangs:

Build at: 2023-02-09T00:51:37.798Z - Hash: 54d6279d114249fc - Time: 9947ms

I'm also using pnpm. Not sure if that matters.

Expected behavior
The CLI exits after build.

Desktop (please complete the following information):

• OS: MacOS
• Version: 12.5.1

Description

Before the NgDoc release, the playground function was removed, because it forced to turn off the aot compilation mode and its API did not quite suit me.

This feature can be extremely useful, especially for the presentation of components and directives, based on the passed class and template, it automatically does the following:

• it automatically determines the list and types of inputs and creates controls for them that you can use to manipulate the value of the input
• generates view and its template based on values of controls
• supports the creation of custom controls for data types that NgDoc cannot detect automatically

Proposed solution

It should be implemented as an additional property in ng-doc.dependencies.ts config file.

import {NgDocDependencies} from '@ng-doc/builder';
import {NgDocTagComponent} from '@ng-doc/ui-kit';

import {PlaygroundPageModule} from './ng-doc.module';

const PlaygroundPageDependencies: NgDocDependencies = {
	// Add your module here
	module: PlaygroundPageModule,
	playgrounds: {
		/**
		 * Playground key that should be used in the template to render the playground
		 */
		TagIconPlayground: {
			/**
			 * The component or directive class that should be rendered
			 */
			target: NgDocTagComponent,
			/**
			 * Template that should be used to render the component playground.
			 * `ng-doc-selector` is dynamic tag that will be replaced with the component selector,
			 * it's required to render the components or directive that have multiple selectors.
			 */
			template: `
			<ng-doc-selector>
				{{iconContent}}
				{{data.label}}
			</ng-doc-selector>`,
			/**
			 * Dynamic content that can be used in the template.
			 * It will be represented as a toggle button in the playground form and added to the
			 * template when it's toggled.
			 */
			dynamicContent: {
				iconContent: {
					label: 'icon',
					template: '<ng-doc-icon icon="info" [size]="16"></ng-doc-icon>'
				}
			},
			/**
			 * Custom data that can be used in the template to fill components with data.
			 */
			data: {
				label: 'Tag Label',
			}
		},
	}
}

export default PlaygroundPageDependencies;

Can be rendered on the page via NgDocActions like that:

## Playground

{{ NgDocActions.playground("TagIconPlayground") }}

So here is an example of how it should work:

Alternatives considered

nope.

Is this a regression?

Yes

Description

Paths are being generated with backslashes on Windows. These are causing compiler errors, rendering the build unusable. Probably because backslash is an escape character on Windows.

Example:

// @ts-nocheck
import {NgDocDemoAssets} from '@ng-doc/app';
import Asset58 from '!!raw-loader!.ng-doc\app\guides\components\button\assets\Asset58.html';
import Asset59 from '!!raw-loader!.ng-doc\app\guides\components\button\assets\Asset59.html';
...
export const demoAssets: NgDocDemoAssets = {
	ButtonPropsComponent: [
		{title: 'TypeScript', codeType: 'TypeScript', code: Asset58},
	],
	ColorsComponent: [
		{title: 'TypeScript', codeType: 'TypeScript', code: Asset59},
	],
}

export default demoAssets;

This wasn't an issue in 15.1.1

Please provide the exception or error you saw

[11:40 PM] 
Error: Module not found: Error: Can't resolve '.ng-docappguidescomponentuttonassetsAsset58.html' in 'C:\Users\-----\Documents\Projects\qui\packages\angular-docs\.ng-doc\app\guides\components\button'

OS

Windows

Browser

None

Node version

18+

Anything else?

No response

Description

At the moment you can configure NgDoc by passing the ngDoc property to configurations for each target in angular.json, which is not really convenient because if you want to have the same configuration for development and for production you have to duplicate it.

Proposed solution

Create one global config, that can be created in the root of a repository something like ng-doc.config.ts, that can be used to configure NgDoc library.

export default {
	pages: 'apps/ng-doc/src/app',
	repoConfig: {
		url: 'https://github.com/skoropadas/ng-doc',
		mainBranch: 'main',
		releaseBranch: 'release',
	},
	keywords: {
		nunjucks: {
			path: 'https://mozilla.github.io/nunjucks/',
		},
		tsdoc: {
			title: 'TsDoc',
			path: 'https://tsdoc.org/',
		},
		highlightjs: {
			title: 'highlight.js',
			path: 'https://highlightjs.org/',
		},
		ngDocFeatureRequest: {
			title: 'NgDoc Feature Request',
			path: 'https://github.com/skoropadas/ng-doc/issues/new?assignees=skoropadas&labels=Type%3A+Enhancement&template=feature_request.yaml&title=%5BFeature%5D+',
		},
	},
};

Alternatives considered

Description

Doc gen sites like Docusaurus and Nextra typically include a prev/next button at the bottom of each page's content. These buttons take the user to the adjacent documentation pages (i.e. the previous or next available sidebar item).

Proposed solution

Add two properties to each NgDocNavigation element in the NgDocContext:

prevRoute: NgDocNavigation
nextRoute: NgDocNavigation

Alternatives considered

I've created a component as a workaround. It flattens the sidebar routes and omits sections that can't be navigated to (e.g. collapsible=true). Then I render a simple component at the bottom of each page.

export class PageLinksComponent implements OnInit, OnDestroy {
  prevLink: NgDocNavigation | undefined
  nextLink: NgDocNavigation | undefined

  eventSub: Subscription

  constructor(
    private router: Router,
    @Inject(NG_DOC_CONTEXT)
    readonly context: NgDocContext,
  ) {}

  ngOnInit() {
    this.collectRoutes(this.context.navigation)
    this.eventSub = this.router.events.subscribe((event) => {
      if (event instanceof NavigationEnd) {
        const url = event.url.split("#")[0]
        this.prevLink = this.getPrevRoute(url)
        this.nextLink = this.getNextRoute(url)
      }
    })
  }

  // flattens the site's available routes to simplify finding the adjacent routes.
  private collectRoutes(routes: NgDocNavigation[]) {
    routes.forEach((route) => {
      // expandable routes don't have a page to navigate to, so we skip them.
      if (!route.expandable) {
        this.routes.push({route: route.route, title: route.title})
      }
      if (route.children) {
        this.collectRoutes(route.children)
      }
    })
  }

  getNextRoute(url: string) {
    const index = this.routes.findIndex((route) => route.route === url)
    if (index === -1) {
      if (isDevMode()) {
        console.error(`Route not found: ${url}`)
      }
      return
    }
    // if on the last route, there is no next route
    if (index === this.routes.length - 1) {
      return
    }
    return this.routes[index + 1]
  }

  getPrevRoute(url: string) {
    const index = this.routes.findIndex((route) => route.route === url)
    if (index === -1) {
      if (isDevMode()) {
        console.error(`Route not found: ${url}`)
      }
      return
    }
    // if on the first route, there is no previous route
    if (index === 0) {
      return
    }
    return this.routes[index - 1]
  }

  ngOnDestroy() {
    this.eventSub?.unsubscribe?.()
  }
}

Describe the bug
NgDoc generates separated pages for classes that have the same name, but the links are all pointing to the same URL

Expected behavior
I guess a better solution will be to add a number for each duplicated type

Desktop (please complete the following information):

• OS: All
• Browser All
• Version All

Description

I'm trying to build a custom search experience on top of ng-doc and I'd like it to be very similar to Nextra's.

Nextra and this library perform the same anchor linking. For every header, anchor links are generated. Nextra takes their search a bit further by parsing the HTML content of every generated page and formatting it into consumable JSON. The site's search then relies on this JSON to produce results that reflect the content of each linkable section:

It's worth noting that this is performed only at build time or in development mode.

Proposed solution

I'm wondering if ng-doc already taps into the content that I'm currently parsing. If so, could it be made available via a service or injection token? If not, how hard would this process be? I could share the code that I'm using to parse each section, although I'm certain that it can be improved.

Alternatives considered

None

Description

I'd like to be able to supply default state to the NgDocActions.demo module. Currently, the following options are static:

1. When a demo opens, it always seems to open on the TypeScript tab. Sometimes I want to open on the HTML tab.
2. When a page first loads, all demo code is collapsed. I'd like the option to set the initial "expanded" state of each demo individually.

Proposed solution

Allow us to supply additional parameters to the demo markdown configuration. Something like the following:

{{ NgDocActions.demo("ButtonDemoComponent", {container: false, initialShow: true, defaultPane: "HTML"}) }}

Alternatives considered

None

Describe the solution you'd like
It is necessary to add automatically generated links to the source code of the guideline or API documentation in the repository, and display them for each page

Description

NgDoc doesn't have a cache, which means that every time the application starts, NgDoc renders and builds the application from scratch. The long build time is particularly noticeable when building an application with many API entities.

Proposed solution

A cache would solve the problem of not having to render what was rendered in the previous build, significantly increasing the speed of subsequent application launches.

Alternatives considered

Is this a regression?

I don't know

Description

After manual installation in empty nx integrated workspace I am experiencing an infinite initialization loop.

Please provide the exception or error you saw

> nx run docs:serve:development

⠼ NgDoc: Initializing...

OS

Windows

Browser

None

Node version

v18.16.0

Anything else?

Same behavior with docs:build:production

Versions:

"@angular/core": "~16.0.0",
"@ng-doc/app": "^16.6.1",
"@ng-doc/builder": "^16.6.1",
"@ng-doc/core": "^16.6.1",
"@ng-doc/ui-kit": "^16.6.1",
"@nx/angular": "16.3.2",
"nx": "16.3.2",
"parsimmon": "^1.18.1",

Description

I think it would be useful to add the following enhancements to playgrounds:

• Directive support
• Pipe support
• Ability to input custom values for template variables

Proposed solution

What is meant by inputting custom values:
This is a kind of list of controls that can be manually created for use with a pipe. For example, a configuration may look as follows:

import {NgDocPage} from '@ng-doc/core';

const MyAwesomePage: NgDocPage = {
  playgrounds: {
    PipePlayground: {
      target: DatePipe,
      template: `{{ values.isoDate | datePipe }}`,
      values: {
        isoDate: 'string',
      }
    },
  },
};

export default MyAwesomePage;

NgDoc will create a control for the "isoDate" field based on the provided type. This will allow the user to input a value and see how it is processed by the pipe. Additionally, if the pipe has additional settings, NgDoc will display a list of them in the Settings section, similar to how it does for components.

For components and directives, this may not be as important since the values of their inputs change through controls in the Settings section, but this values can be used in the template (not for the inputs)

Alternatives considered

Is this a regression?

I don't know

Description

When adding a new demo component to an ng-doc page, the HTML/TypeScript code previews are unavailable until I restart the docs application. The code hide/show button is available, but it doesn't do anything when clicked.

OS

Unix (Linux, macOS, etc.)

Browser

Chrome

Node version

18+

Anything else?

No response

Is this a regression?

No

Description

New Angular 16 feature with required inputs generates wrong results:

@Component({
  selector: "ng-doc-playground-1",
  template: `
		<icon [{ required: true }]="properties['icon']" [size]="properties['size']" [strokeWidth]="properties['strokeWidth']" [color]="properties['color']"></icon>
	`,
  standalone: true,
  imports: [CommonModule, pageEntity.playgrounds["IconPlayground"].target],
  changeDetection: ChangeDetectionStrategy.OnPush,
})

Docs: https://angular.io/api/core/Input

Please provide the exception or error you saw

Error: .ng-doc/docs/guides/docs/playgrounds.ts:18:3 - error NG5002: Opening tag "icon" not terminated.

18   <icon [{ required: true }]="properties['icon']" [size]="properties['size']" [strokeWidth]="properties['strokeWidth']" [color]="properties['color']"></icon>
     ~~~~~~~~~~~~~~~~~~

OS

Unix (Linux, macOS, etc.)

Browser

None

Node version

v18.16.0

Anything else?

Leaving for future improvements 😉

Description

There are situations where I want to keep a docs page on the site, but prevent it from appearing in the sidebar. I'd like this configuration to live at the ng-doc.page.ts level.

Proposed solution

Add sidebar boolean field to NgDocPage interface. When set to false, remove element from sidebar.

Alternatives considered

I've implemented my own sidebar which filters context.navigation, but an official integration would be nice.

Is this a regression?

Yes

Description

The build process doesn't exit, which is causing my CI deployments to fail. This seems to have been introduced in one of the v16.4.x releases.

Please provide the exception or error you saw

No response

OS

Unix (Linux, macOS, etc.)

Browser

None

Node version

18.14.0

Anything else?

No response

Description

At the current moment, we display only one API page for each entity and it's a bit overloaded especially for classes, I think it would be more flexible to start grouping information about entities via tabs.

Proposed solution

For example, Angular Component may have 3 tabs:

• API - should contain basic information about the component, such as a list of members.
• References - should contain links to the current entity as a type or function call, or to the component that is using the current one.
• Framework-specific tab - for Angular, we can display information on which module declared and exports the component, whether it is standalone, and other framework-specific information. We could also add a plugin system in the future to allow users to create custom tabs with the information they want to display.

Alternatives considered