documentation examples loading

[g-cheishvili]

Is this a bug, enhancement, or feature request?

enhancement

Describe your proposal.

In fundamental-ngx documentation pages, in order to show the example codes and also to create the stackblitz links, we have to use some complex approaches, which are easy to mess up. What is happening now is that we need to have a text content of the example files, also their path and their contents. To do that I added example files as assets and for getting the content I just used HttpClient. and the end code, for describing the example file looks something like this

        {
            language: 'html',
            code: getAssetFromModuleAssets('pathtofile.html'),
            fileName: 'file-name-when-outputted'
        },
        {
            language: 'typescript',
            code: getAssetFromModuleAssets('pathtofile.ts'),
            fileName: 'file-name-when-outputted',
            component: 'TheComponentName'
        }

Even though this looks simple, we can not have a autompletion, error reporting and compile-time checks whether the input is correct or not and this leads to the issues on documentation webpage when it's already up! This manual description of the examples also adds the trouble of repetitive work, you have to manually look through the structure and type all the same things all the time. The Storybook has an excellent approach to that, they use custom loaders and story indexers to understand which files contain the examples and they parse them on the fly. So basically what happens is that you write the micromatch of the files, then storybook in compilation goes through the matches and picks up the examples together with their contents in compile-time.

Same behavior can be done in our case as well via custom esbuild plugins, which now can be utilised if we use custom-esbuild builders, instead of the default ones. We can have a configuration on application level, create the structure which will include the map of the doc page and it's examples and then provide that information to the application. This way, the examples will load on it's own, without human interference and less issues.

Why do we need plugin? Simply because otherwise we can not know information about the file system dependencies in the browser and we need that to properly create the stackblitz examples. NodeJS is a must

[g-cheishvili]

This would theoretically result in deletion of the entire {componentName}-docs components, because they will not serve any purpose anymore. The info about the component will be in README.md of that component, the info about particular example's name and the description will come from the markdown of that example.

This would also allow for a dynamic creation of per-example routes in documentation, which in turn will improve the development experience. When you know all the list of the examples in advance, you can patch the router with those example components and then you can have isolated example pages without any additional effort, it just works. This also will allow for better search across the library without any big effort, since you already know the information besides just the names of the components, you can look through that info and report back to user with more depth