SAP Web IDE - New projects now using ui5-tooling

[janmrs]

Hi SAP Community,

As of writing this question, new projects created on SAP Web IDE on the Cloud Platform now use the ui5-tooling modules: ui5-cli, and what looks like a Web IDE-specific version of the ui5-builder module.

Our old projects still use Grunt, where we added an additional task for generating JSDoc documentation.

Is there an immediate need to switch from Grunt to the new ui5-builder? Or will both be supported in the long run?

Also, it doesn't seem like there's an easy option to enable jsdoc, I added the relevant property to my ui5.yaml file (https://github.com/SAP/ui5-project/blob/master/docs/Configuration.md) but nothing was generated. Do I need to create a custom task for this?

Best Regards,
Andre

[merlin_beutlberger]

Indeed the JSDoc generation most would expect (i.e. rendered HTML files), is not yet possible with the UI5 Tooling.

The "ui5 build jsdoc" command creates api.json resources. These (or rather the api-index.json file compiled out of them) can be consumed by the UI5 Demokit Application, as you can see in action at https://ui5.sap.com/#/api.

You can try this yourself by cloning the OpenUI5 repository, changing to the "src/testsuite" directory and executing "npm run build-sdk". Then start an http server for the newly created "dist" directory and open, for example: http://localhost:5000/documentation.html#/api/sap.f.FlexibleColumnLayout

Now for your project: You should already be able to generate api.json files that have content using "ui5 build jsdoc --all". These could be consumed by the SDK build in the OpenUI5 testsuite project. However there is no convenient way of doing that yet.

Our first step was to support building the OpenUI5 SDK with the UI5 Tooling. Next step will be end user consumption for applications and libraries like yours. Apparently there is no ETA for that.

[janmrs]

Since I wanted to try the UI5 Tooling instead of giving up and falling back to Grunt, what I did to generate the JSDoc from Web IDE is to include the jsdoc command line as a dev dependency on my package.json file:

"devDependencies": {
    "@ui5/cli": "1.4.3",
    "@sap/ui5-builder-webide-extension": "1.0.2",
    "jsdoc": "3.6.3"
}

Then following Timo's suggestion on his own answer, I modified the build script to include jsdoc:

"build": "ui5 build --include-task=generateManifestBundle generateCachebusterInfo && jsdoc --verbose -c jsdoc.conf.json"

I have yet to explore the UI5 Tooling extensively, but from what I've read so far, what looks like the proper way to do this is to create a custom task to be invoked during the build process, as explained here: https://github.com/SAP/ui5-project/blob/master/docs/BuildExtensibility.md

[former_member674455]

merlin.beutlberger matthias.osswald Any news on JSDOC generation? Is there an ETA/Entry in some Roadmap?

Tryed `-- include-task= generateJsdoc` aswell as `ui5 build jsdoc`.... Doesn't work like used from `grunt-jsdoc`

Thanks in advance for an answer!

[former_member674455]

Figured out a solution: How to generate an JSDoc documentation for your UI5 application in the SAP Web IDE (UI5 Tooling & Gr...

[beanonradar]

Jsdoc generation is a seperate build process and can be called via ui5 cli with "ui5 build jsdoc" see also "ui5 build --help". In Web IDE (package.json)

    "build": "ui5 build --include-task=generateManifestBundle generateCachebusterInfo generateJsdoc"

unfortunately does not work. The following works but I don't know if it should be used that way:

    "build": "ui5 build --include-task=generateManifestBundle generateCachebusterInfo && ui5 build jsdoc"

Then you can find you doc folder inside the dist folder.

[janmrs]

I see. This is my first time trying out the new ui5 builder tool, I didn't realize there was a separate build command for jsdoc. I tried the two commands on both Web IDE and my local machine, the first one really doesn't work like you said, the second one worked but all I got was .json files (which looks empty, by the way):

{"$schema-ref":"http://schemas.sap.com/sapui5/designtime/api-index.json/1.0","version":"0.0.1","library":"*","symbols":[]}

Unfortunately I'm not sure how to generate jsdoc files in HTML format with this new tool.

[beanonradar]

You are right. The files are empty. The only usage examples I found here:

https://github.com/SAP/openui5/blob/master/docs/developing.md

Maybe the jsodoc build mode is meant for openui5 core development and not for ui5 apps. I'm a bit lost now and hope someone else can help out.