cleanup typescript.asciidoc

docs/developer/best-practices/typescript.asciidoc

@@ -3,10 +3,8 @@
 
 Although this is not a requirement, we encourage if all new code is developed in https://www.typescriptlang.org/[Typescript].
 
-<<project-references>>
-
-[[project-references]]
-== Project references
+[discrete]
+=== Project references
 Kibana has crossed the 2m LoC mark. The current situation creates some scaling problems when the default out-of-the-box setup stops working. As a result, developers suffer from slow project compilation and IDE unresponsiveness. As a part of https://github.com/elastic/kibana/projects/63[Developer Experience project], we are migrating our tooling to use built-in TypeScript features addressing the scaling problems - https://www.typescriptlang.org/docs/handbook/project-references.html[project references] & https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#faster-subsequent-builds-with-the---incremental-flag[incremental builds]
 
 In a nutshell - instead of compiling the whole Kibana codebase at once, this setup enforces splitting the code base into independent projects that form a directed acyclic graph (DAG). This allows the TypeScript compiler (`tsc`) to apply several advanced optimizations:
@@ -17,7 +15,8 @@ In a nutshell - instead of compiling the whole Kibana codebase at once, this set
 
 More details are available in the https://www.typescriptlang.org/docs/handbook/project-references.html[official docs]
 
-=== Caveats
+[discrete]
+==== Caveats
 This architecture imposes several limitations to which we must comply:
 
 - Projects cannot have circular dependencies. Even though the Kibana platform doesn't support circular dependencies between Kibana plugins, TypeScript (and ES6 modules) does allow circular imports between files. So in theory, you may face a problem when migrating to the TS project references and you will have to resolve this circular dependency.
@@ -26,13 +25,16 @@ This architecture imposes several limitations to which we must comply:
 1. Your plugin exports a type inferring an internal type declared in Kibana codebase. In this case, you'll have to either export an internal type or to declare an exported type explicitly.
 2. Your plugin exports something inferring a type from a 3rd party library that doesn't export this type. To fix the problem, you have to declare the exported type manually.
 
-=== Prerequisites
+[discrete]
+==== Prerequisites
 Since `tsc` doesn't support circular project references, the migration order does matter. You can migrate your plugin only when all the plugin dependencies already have migrated. It creates a situation where commonly used plugins (such as `data` or `kibana_react`) have to migrate first.
 
-=== Implementation
+[discrete]
+==== Implementation
 1. Make sure all the plugins listed as dependencies in `kibana.json` file have migrated to TS project references.
 1. Add `tsconfig.json` in the root folder of your plugin.
-```json
+[source,json]
+----
 {
   "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
@@ -50,7 +52,7 @@ Since `tsc` doesn't support circular project references, the migration order doe
     // add references to other TypeScript projects your plugin dependes on
   ]
 }
-```
+----
 If your plugin imports a file not listed in `include`, the build will fail with the next message `File ‘…’ is not listed within the file list of project …’. Projects must list all files or use an 'include' pattern.`
 [start=3]
 1. Build you plugin `./node_modules/.bin/tsc -b src/plugins/my_plugin`. Fix errors if `tsc` cannot generate type declarations for your project.