chore: Fix docs for latest version of typedoc (#889)

* chore: Fix docs for latest version of typedoc

* adjust search.js instead of search.json

Co-authored-by: Junjie Tang <[email protected]>

CONTRIBUTING.md

@@ -7,7 +7,7 @@ All dependencies that are used in more than one of the packages are hoisted into
 
 ## Testing
 In order to run all tests, execute:
-```sh-session
+```bash
 $ yarn test
 ```
 
@@ -16,20 +16,20 @@ This will run unit tests for all our packages as well as integration tests and t
 ### Unit Tests
 Unit tests shall test specific modules of a package, units that are tested for behavior.
 You can run all unit tests by executing:
-```sh-session
+```bash
 $ yarn test:unit
 ```
 
 To run unit tests for a specific package add the workspace name to the command. For the core package this would be:
-```sh-session
+```bash
 $ yarn @sap-cloud-sdk/core run test
 ```
 
 ### Integration Tests
 Integration tests shall test how modules behave in combination. The integration tests are located in [`test-packages/integration-tests`](./test-packages/integration-tests).
 
 To run the integration tests, execute:
-```sh-session
+```bash
 $ yarn test:integration
 ```
 
@@ -38,7 +38,7 @@ As this project is written in TypeScript, it shall be consumable by other TypeSc
 The type tests are located at [`test-packages/type-tests`](./test-packages/type-tests).
 
 To run the integration tests, execute:
-```sh-session
+```bash
 $ yarn test:type
 ```
 
@@ -51,27 +51,27 @@ First, we generate type script sources, that are generated into the test-utils o
 Second, we generate a transpiled version of a non-modified OData client based on the specifications, that is located at [`test-packages/test-services`](./test-packages/test-services). This is used in the integration tests and type tests.
 
 If you need to extend the existing services, run the following to regenerate the OData clients.
-```sh-session
+```bash
 $ yarn generate:test-services
 ```
 
 ### End to End (E2E) tests
 
 The E2E are the most realistic tests included in this repo and run on each pull request.
 There are also nightly tests executed on the internal jenkins - see the internal repo for more details on these.
-These are also called E2E tests but are not meant here. 
+These are also called E2E tests but are not meant here.
 
 The E2E tests are based on a locally running server providing an OData interface using [CAP](https://cap.cloud.sap/docs/) and a Rest interface using OpenApi.
 This server is used by the E2E tests located at [test-packages/e2e-tests](./test-packages/e2e-tests).
 **Attention** The imports in the E2E tests use the root packages e.g. `@sap-cloud-sdk/core` to mimic the way a customer would use it.
-So if you made code changes in one of the packages you need to run `yarn compile` to make the changes take effect.  
+So if you made code changes in one of the packages you need to run `yarn compile` to make the changes take effect.
 
 For manual E2E to a real remote system we have also some tests agains the [TripPin service](https://www.odata.org/blog/trippin-new-odata-v4-sample-service/) which is the standard OData V4 sample service.
 Since the remote service is not really stable we commented out the tests under [test-packages/e2e-tests/test/TripPin](./test-packages/e2e-tests/test/TripPin) but for manual testing they can be useful.
 
 ## Linting
 To fix all linting issues, run:
-```sh-session
+```bash
 $ yarn lint:fix
 ```
 

README.md

@@ -30,23 +30,23 @@ To use the SDK in your project, we recommend using our [commandline interface](#
 The core is the heart of the SAP Cloud SDK and contains the functionality that is essential to every project powered by the SDK. Any OData client built by the SAP Cloud SDK, be it the VDM or clients built by the generator are using the core. We recommend to install this in addition to your clients.
 
 To install the SAP Cloud SDK core in your project, run:
-```sh-session
+```bash
 $ npm install @sap-cloud-sdk/core
 ```
 
 ### @sap-cloud-sdk/generator
 The SAP Cloud SDK generator is a command line interface (CLI) that allows you to create clients for your own OData services or other SAP systems besides SAP S/4HANA based on their service specifications.
 
 To install the SAP Cloud SDK generator in your project, run:
-```sh-session
+```bash
 $ npm install @sap-cloud-sdk/generator
 ```
 
 ### @sap-cloud-sdk/test-util
 The test-util package makes writing tests for your SAP Cloud Platform application more convenient.
 
 To install the SAP Cloud SDK test-util as development dependencies in your project, run:
-```sh-session
+```bash
 $ npm install -D @sap-cloud-sdk/test-util
 ```
 
@@ -64,7 +64,7 @@ In addition to the Open Source parts of this project, we also publish the SAP Cl
 
 To install an OData client for an SAP S/4HANA service run:
 
-```sh-session
+```bash
 $ npm install @sap/cloud-sdk-vdm-<service name>-service
 ```
 In the example above, `service name` is the name of the service you want to use, e. g. for the business partner service, run: `npm install @sap/cloud-sdk-vdm-business-partner-service`.

package.json

@@ -1,5 +1,6 @@
 {
   "name": "sap-cloud-sdk",
+  "version": "1.34.0",
   "private": true,
   "sideEffects": false,
   "description": "SAP Cloud SDK for JavaScript",
@@ -82,8 +83,7 @@
     "prettier": "^2.0.2",
     "ts-jest": "^26.4.1",
     "ts-node": "^9.0.0",
-    "typedoc": "^0.20.0",
-    "typedoc-plugin-lerna-packages": "0.3.0",
+    "typedoc": "^0.20.13",
     "typescript": "~4.1.2"
   },
   "dependencies": {},

packages/analytics/src/index.ts

@@ -1,3 +1,9 @@
+/**
+ * [[include:analytics/README.md]]
+ * @packageDocumentation
+ * @module @sap-cloud-sdk/analytics
+ */
+
 export * from './analytics-data';
 export * from './usage-analytics';
 export * from './config';

packages/core/src/index.ts

@@ -1,3 +1,9 @@
+/**
+ * [[include:core/README.md]]
+ * @packageDocumentation
+ * @module @sap-cloud-sdk/core
+ */
+
 export * from './connectivity';
 export * from './header-util';
 export * from './http-client';

packages/core/src/odata-common/filter/filterable.ts

@@ -27,7 +27,7 @@ export type Filterable<EntityT extends Entity> =
  *  .filter(and(filterExp1, filterExp2));
  * ```
  *
- * Note that the [[GetAllRequestBuilderV2.filter]]  and [[GetAllRequestBuilderV4.filter]] method take a rest parameter and thereby an array of filter expressions that are then combined conjunctively. As a consequence following is equivalent to the example above:
+ * Note that the [[GetAllRequestBuilder.filter | GetAllRequestBuilderV2.filter]]  and [[GetAllRequestBuilderV4.filter]] method take a rest parameter and thereby an array of filter expressions that are then combined conjunctively. As a consequence following is equivalent to the example above:
  * ```ts
  * Entity.requestBuilder()
  *  .getAll()

packages/core/src/odata-common/index.ts

@@ -12,6 +12,7 @@ export * from './time';
 export * from './uri-conversion';
 export * from './expandable';
 export * from './entity-deserializer';
+export * from './entity-serializer';
 export * from './payload-value-converter';
 export * from './name-converter';
 export * from './properties-util';

packages/core/src/odata-common/selectable/link.ts

@@ -73,7 +73,7 @@ export class Link<EntityT extends Entity, LinkedEntityT extends Entity = any>
   ) {}
 
   /**
-   * Creates a selection on a linked entity. Has the same behavior as [[GetAllRequestBuilderV2.select]] and [[GetByKeyRequestBuilderV4.select]] but for linked entities.
+   * Creates a selection on a linked entity. Has the same behavior as [[GetAllRequestBuilder.select | GetAllRequestBuilderV2.select]] and [[GetByKeyRequestBuilderV4.select]] but for linked entities.
    *
    * See also, [[Selectable]]
    *

packages/core/src/odata-v2/uri-conversion/get-filter.ts

@@ -3,7 +3,7 @@ import { Constructable, Filterable } from '../../odata-common';
 import { oDataUri } from './odata-uri';
 
 /**
- * @deprecated Since v1.21.0. Use [[oDataUri.getFilter]] instead.
+ * @deprecated Since v1.21.0. Use [[ODataUri.getFilter]] instead.
  * Get an object containing the given filter as query parameter, or an empty object if none was given.
  *
  * @typeparam EntityT - Type of the entity to filter on

packages/core/src/odata-v2/uri-conversion/get-orderby.ts

@@ -2,7 +2,7 @@ import { getOrderBy, Orderable } from '../../odata-common';
 import { Entity } from '../entity';
 
 /**
- * @deprecated Since v1.21.0. Use [[oDataUri.getOrderBy]] instead.
+ * @deprecated Since v1.21.0. Use [[ODataUri.getOrderBy]] instead.
  * Get an object containing the given order bys as query parameter, or an empty object if none was given.
  *
  * @typeparam EntityT - Type of the entity to order

packages/core/src/odata-v2/uri-conversion/get-resource-path.ts

@@ -6,7 +6,7 @@ import {
 import { oDataUri } from './odata-uri';
 
 /**
- * @deprecated Since v1.21.0. Use [[oDataUri.getResourcePathForKeys]] instead.
+ * @deprecated Since v1.21.0. Use [[ODataUri.getResourcePathForKeys]] instead.
  * Get the resource path of an entity specified by key-value pairs.
  *
  * @typeparam EntityT - Type of the entity to get the resource path for

packages/core/src/odata-v2/uri-conversion/get-selection.ts

@@ -4,7 +4,7 @@ import { getSelect } from './get-select';
 import { getExpand } from './get-expand';
 
 /**
- * @deprecated Since v1.21.0. Use [[oDataUri.getSelect]] and [[oDataUri.getExpand]] instead.
+ * @deprecated Since v1.21.0. Use [[ODataUri.getSelect]] and [[ODataUri.getExpand]] instead.
  *
  * Get an object containing the given Selectables as query parameter, or an empty object if none were given.
  * This retrieves where in addition to the selection (`select`) there is also an expansion (`expand`) needed.

packages/core/src/odata-v4/request-builder/get-by-key-request-builder.ts

@@ -12,8 +12,8 @@ import { oDataUri } from '../uri-conversion';
 import { responseDataAccessor } from './response-data-accessor';
 /**
  * Create an OData request to get a single entity based on its key properties.
- * The properties available in the response can be restricted by creating a [[GetByKeyRequestBuilder.select selection]], where no selection is equal to selecting all fields of the entity.
- * Navigational properties need to expanded explicitly by [[GetAllRequestBuilder.expand]].
+ * The properties available in the response can be restricted by creating a [[GetByKeyRequestBuilderV4.select selection]], where no selection is equal to selecting all fields of the entity.
+ * Navigational properties need to expanded explicitly by [[GetAllRequestBuilderV4.expand]].
  * where no selection is equal to selecting all fields.
  *
  * @typeparam EntityT - Type of the entity to be requested

packages/core/tsconfig.json

@@ -15,6 +15,7 @@
     "**/*.spec.ts",
     "node_modules/**/*"
   ],
+  "files": [],
   "references": [
     {"path": "../util"},
     {"path": "../analytics"}

packages/generator/src/index.ts

@@ -1,2 +1,8 @@
+/**
+ * [[include:generator/README.md]]
+ * @packageDocumentation
+ * @module @sap-cloud-sdk/generator
+ */
+
 export * from './generator';
 export * from './generator-options';

packages/generator/tsconfig.json

@@ -3,7 +3,8 @@
   "compilerOptions": {
     "rootDir": "./src",
     "outDir": "./dist",
-    "tsBuildInfoFile": "./dist/.tsbuildinfo"
+    "tsBuildInfoFile": "./dist/.tsbuildinfo",
+    "composite": true
   },
   "include": [
     "src/**/*.ts"

packages/openapi-generator/README.md

@@ -8,7 +8,7 @@ This generator is based on the [OpenAPI Tools generator](https://openapi-generat
 The official OpenAPI generator is Java based, therefore you need to have a Java runtime installed to use the SAP Cloud SDK OpenAPI generator.
 
 # Installation
-```sh-session
+```bash
 $ npm install @sap-cloud-sdk/openapi-generator
 ```
 # Usage (CLI)

packages/openapi-generator/src/index.ts

@@ -1,3 +1,7 @@
-/* Copyright (c) 2020 SAP SE or an SAP affiliate company. All rights reserved. */
+/**
+ * [[include:openapi-generator/README.md]]
+ * @packageDocumentation
+ * @module @sap-cloud-sdk/openapi-generator
+ */
 
 export { generate } from './generator';

packages/openapi-generator/tsconfig.json

@@ -3,10 +3,11 @@
   "compilerOptions": {
     "rootDir": "./src",
     "outDir": "./dist",
-    "target": "es2017"
+    "tsBuildInfoFile": "./dist/.tsbuildinfo",
+    "composite": true
   },
   "include": [
-    "src/**/*.ts", "test/emptyApiDefinition.ts"
+    "src/**/*.ts"
   ],
   "exclude": [
     "dist/**/*",

packages/test-util/src/index.ts

@@ -1,2 +1,8 @@
+/**
+ * [[include:test-util/README.md]]
+ * @packageDocumentation
+ * @module @sap-cloud-sdk/test-util
+ */
+
 export * from './test-destination-provider';
 export * from './test-destination-mocker';

packages/util/src/index.ts

@@ -1,3 +1,9 @@
+/**
+ * [[include:util/README.md]]
+ * @packageDocumentation
+ * @module @sap-cloud-sdk/util
+ */
+
 export * from './array';
 export * from './code-block';
 export * from './constants';

scripts/after-bump.js

@@ -1,6 +1,15 @@
 const path = require('path');
 const { transformFile, version, jsonStringify, apiDocsDir } = require('./util');
 
+function updateRootPackageJson() {
+  transformFile(path.resolve('package.json'), packageJson =>
+    jsonStringify({
+      ...JSON.parse(packageJson),
+      version: `${version}`
+    })
+  );
+}
+
 function updateDocumentationMd() {
   transformFile(path.resolve('DOCUMENTATION.md'), documentation =>
     documentation
@@ -13,12 +22,16 @@ function updateDocumentationMd() {
 }
 
 function updateTypeDocConfig() {
-  transformFile('typedoc.json', config =>
-    jsonStringify({
-      ...JSON.parse(config),
-      out: `${path.relative(path.resolve(), apiDocsDir)}/${version}`
-    })
-  );
+  transformFile('tsconfig.typedoc.json', config => {
+    const parsedConfig = JSON.parse(config);
+    return jsonStringify({
+      ...parsedConfig,
+      typedocOptions: {
+        ...parsedConfig.typedocOptions,
+        out: `${path.relative(path.resolve(), apiDocsDir)}/${version}`
+      }
+    });
+  });
 }
 
 function updateDocsVersions() {
@@ -81,6 +94,7 @@ function updateChangelog() {
 }
 
 function afterBump() {
+  updateRootPackageJson();
   updateDocumentationMd();
   updateTypeDocConfig();
   updateDocsVersions();

scripts/generate-docs.js

@@ -24,7 +24,7 @@ const readDir = inputDir =>
   )(inputDir);
 
 const isHtmlFile = fileName => path.extname(fileName) === '.html';
-const isSearchJson = fileName => path.basename(fileName) === 'search.json';
+const isSearchJs = fileName => path.basename(fileName) === 'search.js';
 const pipe = (...fns) => start => fns.reduce((state, fn) => fn(state), start);
 
 /**
@@ -50,7 +50,7 @@ function adjustForGitHubPages() {
 }
 
 function adjustSearchJs(paths) {
-  const filtered = paths.filter(isSearchJson);
+  const filtered = paths.filter(isSearchJs);
   if (filtered.length !== 1) {
     throw Error(`Expected one 'search.json', but found: ${filtered.length}.`);
   }
@@ -139,7 +139,7 @@ function validateLogs(generationLogs) {
 }
 
 function generateDocs() {
-  const generationLogs = execSync('npx typedoc .', {
+  const generationLogs = execSync('typedoc --tsconfig tsconfig.typedoc.json', {
     cwd: path.resolve(),
     encoding: 'utf8'
   });