Question about ng-doc integration into your app

[edumserrano]

Hi,

I've been reading through the documentation and I'm trying to understand a few concepts:

1. Suppose I already have an angular app and I want to add ng-doc, after I follow the installation guide, won't that mean that when I bundle my angular app the ng-doc will also be bundled with it? I'm asking cause I was thinking of adding ng-doc as a way to add documentation pages to help developers work with the codebase but I don't want to expose those docs when I publish and deploy the app.

2. I have an existing angular app where I've add to extend angular's webpack process. I did it by using ngx-build-plus and replaced the serve:builder with ngx-build-plus:dev-server which then allowed me to extend the default webpack configuration via the ngx-build-plus new property named extraWebpackConfig where I passed a JS file to do what I needed.

After reading the docs, when using ng-doc I have to change the builders on my angular.json file to use the ng-doc's builders. Would I still be able to pass extra webpack configuration in any in this scenario?

[edumserrano]

Perhaps my confusion is this part at the start of the installation guide:

Before installing the library, you will need the Angular application that you will use to display your documentation.

Does it mean to say that I should have a new angular app just for the docs? And then I reference things from my "real" app in the docs app module? Is that it?

[skoropadas]

Overall, yes, initially it was assumed that you would need to create a separate application to display the documentation, in which you would describe the process of working with the library or application and everything necessary.

I think the documentation for the application can be created as a separate application. It should not be a problem if you are using a monorepo. This way, you will gain flexibility. For example, you can publish it on a specific domain for developers only and have faster builds.

It is also important to understand that I mentioned the monorepo not by chance because NgDoc requires access to the source code for proper functioning. NgDoc cannot generate documentation or display demos based on compiled code and source maps.

If we are talking about a single application where both the documentation and the application itself exist simultaneously, while the documentation is excluded from production builds, I believe it is possible. You can exclude a part of the application using fileReplacements in the angular.json file and routing.

However, as you mentioned earlier, you have a custom webpack configuration that NgDoc does not currently allow customization for. I need to think about it because I'm not sure at the moment if I want to add this functionality, as Angular does not officially support it, and NgDoc supports both Webpack and EsBuild as builders. Supporting custom webpack configuration could be problematic in the future. 🤔

[edumserrano]

This clarifies it for me. Thank you!

As a suggestion I'd say the docs could use some clarification on this point. I've been reading through https://ng-doc.com/docs/getting-started/what-is-ng-doc and these things weren't immediately obvious to me.

And as you've said, I was thinking I could probably have the docs in the app and do some angular magic to exclude it from the final build as well as separate the ng-doc stuff into it's own module (as hinted in parts of the docs). However I wasn't sure what was the intention/the recommended path.

I think an extension of the docs to clarify this and your comment about making sure the docs app is on the same repo as the app it is documenting is important. Perhaps obvious to some but I think it's a worth addition to the docs.

PS- If you do decide to update the docs I would avoid using the word monorepo since I've had colleagues react negatively to anything associated to that word. Plus, in your comment I believe you only used that word to mean that both the docs app and the app being documented must be in the same repo, not that necessarily there would be many more apps in the repo.

[skoropadas]

About "monorepo" - you are absolutely right! 😄 I will definitely update the documentation and add more information. Tickets and questions like these give me a better understanding of what users find unclear and where I should improve my documentation. Thank you for that!

[edumserrano]

Regarding the support for extra webpack config. As you've said that goes away as soon as I create a separate app for the docs so I'm not sure there's even a real need here to be fulfilled.

Perhaps it would be wise to hold on it until you get more people asking about it?

[skoropadas]

It makes sense for sure! Thank you for understanding :)