[Doc] Use template variables for all snippet/example links

tbuschto · tbuschto · commit 4d961a66f384 · 2021-07-19T15:39:54.000+02:00
Absolute urls to tabris resources should be avoided in hand-written
documentation. This change adds support for additional template
variables that insert github urls.

Added a README.md in the "tools" directory explaining which variables
are available.

Change-Id: I0eaf154a94fd0888f348795acff65aec8d4ffdd2
diff --git a/doc/api/Cell.json b/doc/api/Cell.json
@@ -20,7 +20,7 @@
       ]
     },
     "namespace": false,
-    "description": "This widget is expected by [`ListView`](./ListView.md) as a child (in JSX) or turn value of `createCell`. It's data-binding enabled by default. It's children can also [not be selected](../selector.md#encapsulation) from the outside, except for using `apply` directly on the instance. This allows using it as a function component as demonstrated in [this example](https://github.com/eclipsesource/tabris-decorators/tree/v${doc:moduleversion}/examples/listview-cells-js).",
+    "description": "This widget is expected by [`ListView`](./ListView.md) as a child (in JSX) or turn value of `createCell`. It's data-binding enabled by default. It's children can also [not be selected](../selector.md#encapsulation) from the outside, except for using `apply` directly on the instance. This allows using it as a function component as demonstrated in [this example](${doc:listview-cells-js}).",
     "properties": {
       "item": {
         "type": "ItemType",
diff --git a/doc/api/ColorResources.json b/doc/api/ColorResources.json
@@ -16,11 +16,11 @@
     },
     {
       "title": "Defining raw color resource data in a separate JSON file.",
-      "path": "https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/snippets/resources/colors.json"
+      "path": "${doc:snippetsUrl}/resources/colors.json"
     },
     {
       "title": "Converting raw color resource data to `ColorResources` instance.",
-      "path": "https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/snippets/resources/index.ts"
+      "path": "${doc:snippetsUrl}/resources/index.ts"
     },
     {
       "title": "Using a ColorResources dictionary",
@@ -76,7 +76,7 @@
             {
               "name": "data",
               "type": "Data",
-              "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js colors JSON schema](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/schema/colors.json)."
+              "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js colors JSON schema](${doc:colors.json})."
             }
           ],
           "returns": "ColorResources",
@@ -105,7 +105,7 @@
             {
               "name": "data",
               "type": "Data",
-              "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js colors JSON schema](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/schema/colors.json)."
+              "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js colors JSON schema](${doc:colors.json})."
             }
           ],
           "returns": "ColorResources",
@@ -116,7 +116,7 @@
               "keyof Data"
             ]
           },
-          "description": "Creates a colors dictionary from the given raw \"data\" object. The format must match the [Tabris.js colors JSON schema](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/schema/colors.json). Entries in the \"data\" object starting with \"$\" are considered configuration options and will not become entries in the final colors dictionary."
+          "description": "Creates a colors dictionary from the given raw \"data\" object. The format must match the [Tabris.js colors JSON schema](${doc:colors.json}). Entries in the \"data\" object starting with \"$\" are considered configuration options and will not become entries in the final colors dictionary."
         }
       ]
     }
diff --git a/doc/api/FontResources.json b/doc/api/FontResources.json
@@ -16,11 +16,11 @@
     },
     {
       "title": "Defining raw font resource data in a separate JSON file.",
-      "path": "https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/snippets/resources/fonts.json"
+      "path": "${doc:snippetsUrl}/resources/fonts.json"
     },
     {
       "title": "Converting raw font resource data to `FontResources` instance.",
-      "path": "https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/snippets/resources/index.ts"
+      "path": "${doc:snippetsUrl}/resources/index.ts"
     },
     {
       "title": "Using a FontResources dictionary",
@@ -76,7 +76,7 @@
             {
               "name": "data",
               "type": "Data",
-              "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js fonts JSON schema](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/schema/fonts.json)."
+              "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js fonts JSON schema](${doc:fonts.json})."
             }
           ],
           "returns": "FontResources",
@@ -105,7 +105,7 @@
             {
               "name": "data",
               "type": "Data",
-              "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js fonts JSON schema](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/schema/fonts.json)."
+              "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js fonts JSON schema](${doc:fonts.json})."
             }
           ],
           "returns": "FontResources",
@@ -116,7 +116,7 @@
               "keyof Data"
             ]
           },
-          "description": "Creates a fonts dictionary from the given raw \"data\" object. The format must match the [Tabris.js fonts JSON schema](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/schema/fonts.json). Entries in the \"data\" object starting with \"$\" are considered configuration options and will not become entries in the final fonts dictionary."
+          "description": "Creates a fonts dictionary from the given raw \"data\" object. The format must match the [Tabris.js fonts JSON schema](${doc:fonts.json}). Entries in the \"data\" object starting with \"$\" are considered configuration options and will not become entries in the final fonts dictionary."
         }
       ]
     }
diff --git a/doc/api/TextResources.json b/doc/api/TextResources.json
@@ -16,11 +16,11 @@
     },
     {
       "title": "Defining raw text resource data in a separate JSON file.",
-      "path": "https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/snippets/resources/texts.json"
+      "path": "${doc:texts.json}"
     },
     {
       "title": "Converting raw text resource data to `TextResources` instance.",
-      "path": "https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/snippets/resources/index.ts"
+      "path": "${doc:snippetsUrl}/resources/index.ts"
     },
     {
       "title": "Using a TextResources dictionary",
@@ -76,7 +76,7 @@
             {
               "name": "data",
               "type": "Data",
-              "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js texts JSON schema](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/schema/texts.json)."
+              "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js texts JSON schema](${doc:texts.json})."
             }
           ],
           "returns": "TextResources",
@@ -105,7 +105,7 @@
             {
               "name": "data",
               "type": "Data",
-              "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js texts JSON schema](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/schema/texts.json)."
+              "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js texts JSON schema](${doc:texts.json})."
             }
           ],
           "returns": "TextResources",
@@ -116,7 +116,7 @@
               "keyof Data"
             ]
           },
-          "description": "Creates a texts dictionary from the given raw \"data\" object. The format must match the [Tabris.js texts JSON schema](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/schema/texts.json). Entries in the \"data\" object starting with \"$\" are considered configuration options and will not become entries in the final texts dictionary."
+          "description": "Creates a texts dictionary from the given raw \"data\" object. The format must match the [Tabris.js texts JSON schema](${doc:texts.json}). Entries in the \"data\" object starting with \"$\" are considered configuration options and will not become entries in the final texts dictionary."
         }
       ]
     }
diff --git a/doc/declarative-ui.md b/doc/declarative-ui.md
@@ -328,10 +328,10 @@ const StyledText = attributes => TextView({textColor: 'red', ...attributes}, Sty
 
 You can find further example snippets for functional components here:
 
-* [JavaScript/JSX](https://playground.tabris.com/?snippet=functional-jsx-components.jsx)
-* [Pure JavaScript](https://playground.tabris.com/?snippet=functional-js-components.js)
-* [TypeScript/JSX](https://playground.tabris.com/?snippet=functional-jsx-components-typescript.tsx)
-* [Pure TypeScript](https://playground.tabris.com/?snippet=functional-js-components-typescript.tsx)
+* [JavaScript/JSX](${doc:functional-jsx-components.jsx})
+* [Pure JavaScript](${doc:functional-js-components.js})
+* [TypeScript/JSX](${doc:functional-jsx-components-typescript.jsx})
+* [Pure TypeScript](${doc:functional-js-components-typescript.js})
 
 There are two categories of functional components, stateless and dynamic:
 
@@ -373,7 +373,7 @@ function PersonDataView(attr) {
 }
 ```
 
-> You can also use the `<Setter>` element to define the change listener as seen [here for JavaScript/JSX](https://playground.tabris.com/?snippet=functional-jsx-components.jsx) and [here for TypeScript/JSX](https://playground.tabris.com/?snippet=functional-jsx-components-typescript.tsx).
+> You can also use the `<Setter>` element to define the change listener as seen [here for JavaScript/JSX](${doc:functional-jsx-components.jsx}) and [here for TypeScript/JSX](${doc:functional-jsx-components-typescript.tsx}).
 
 The usage is as you would expect:
 
diff --git a/doc/developer-app.md b/doc/developer-app.md
@@ -23,7 +23,7 @@ Here you'll find a collection of example scripts that you can modify and try on
 
 To load the playground script in your Developer App, go to the "URL" tab on the home screen and scan the QR code on the playground page. When you edit the code in the playground you only need to reload via the developer console or scan the QR code again.
 
-You can also add your own scripts to the list by pressing "save". Note that these are stored only on your machine and will be lost if you clear your browser user data. The snippets [are also available in the tabris git repository](https://github.com/eclipsesource/tabris-js/tree/master/snippets).
+You can also add your own scripts to the list by pressing "save". Note that these are stored only on your machine and will be lost if you clear your browser user data. The snippets [are also available in the tabris git repository](${doc:snippetsUrl}).
 
 ## Code Sideloading
 
diff --git a/doc/examples.md b/doc/examples.md
@@ -4,7 +4,7 @@
 
 ## Snippets
 
-The `tabris-js` [repository](https://github.com/eclipsesource/tabris-js) contains dozens of [self-running snippets](https://github.com/eclipsesource/tabris-js/tree/v${doc:moduleversion}/snippets) demonstrating all **features of the Tabris.js core module**. These can be run directly from the [Tabris.js Playground](https://playground.tabris.com/) via the [Tabris.js Developer App](./developer-app.md). The API documentation example links point to the snippets in the playground.
+The `tabris-js` [repository](https://github.com/eclipsesource/tabris-js) contains dozens of [self-running snippets](${doc:snippetsUrl}) demonstrating all **features of the Tabris.js core module**. These can be run directly from the [Tabris.js Playground](https://playground.tabris.com/) via the [Tabris.js Developer App](./developer-app.md). The API documentation example links point to the snippets in the playground.
 
 You can also run a selection of UI-related snippets directly in the app without the playground.
 
@@ -13,7 +13,7 @@ All snippets use declarative UI and ES6 Module Syntax. Most also use JSX, and so
 ## Databinding Examples
 
 The `tabris-decorators` [repository](https://github.com/eclipsesource/tabris-decorators) contains minimalistic
-[**databinding** and **redux** examples](https://github.com/eclipsesource/tabris-decorators/tree/v${doc:moduleversion}/examples) as complete tabris projects. The **ListView** and **ItemPicker** widgets (high-level extensions of `CollectionView` and `Picker`) are also demonstrated only here. They are also linked in the databinding documentation.
+[**databinding** and **redux** examples](${doc:examplesUrl}) as complete tabris projects. The **ListView** and **ItemPicker** widgets (high-level extensions of `CollectionView` and `Picker`) are also demonstrated only here. They are also linked in the databinding documentation.
 
 The examples can be easily run without local setup via the GitPod links provided in the README.md files. A GitHub account is required. The READMEs also contain comprehensive descriptions for each example.
 
diff --git a/doc/getting-started.md b/doc/getting-started.md
@@ -45,7 +45,7 @@ In the project directory, type `npm start`. This will start the development serv
 
 Swipe from the right edge of the screen to open the developer console, which lets you restart the script or go back to the Developer App.
 
-Now you can start developing. You may want to have a look at the rest of the documentation and [the Tabris.js snippets](https://github.com/eclipsesource/tabris-js/tree/master/snippets).
+Now you can start developing. You may want to have a look at the rest of the documentation and [the Tabris.js snippets](${doc:snippetsUrl}).
 
 ## Publishing your app
 
diff --git a/doc/permissions.md b/doc/permissions.md
@@ -203,7 +203,7 @@ async function requestPermissions(...permissions) {
 
 The following snippets demonstrate how to use the `tabris.permission` API.
 
-* [permission.jsx](https://playground.tabris.com/?gitref=v3.1.0&snippet=permission.jsx)
-* [permission-advanced.tsx](https://playground.tabris.com/?gitref=v3.1.0&snippet=permission-advanced.tsx)
+* [permission.jsx](${doc:permission.jsx})
+* [permission-advanced.tsx](${doc:permission-advanced.tsx})
 
 Also see the [Android](https://developer.android.com/guide/topics/permissions/overview) and [iOS](https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/requesting-permission/) documentation on permission.
diff --git a/doc/resource-management.md b/doc/resource-management.md
@@ -64,7 +64,7 @@ Create a separate directory dedicated to your resource dictionaries. The example
 
 If your project has a `tsconfig.json` or `jsconfig.json` make sure it contains the compiler option `"resolveJsonModule": true`. This makes it possible to consume the _.json_ files as modules without loosing type safety.
 
-The `index.js` (or `index.ts`) module will take care of converting the raw data to resources dictionaries and exporting them from the `resources` directory. (Hint: A file named "index.js" allows [treating an entire directory as a single module](https://nodejs.org/api/modules.html#modules_folders_as_modules).) An example for this can be found [here](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/snippets/resources/index.ts).
+The `index.js` (or `index.ts`) module will take care of converting the raw data to resources dictionaries and exporting them from the `resources` directory. (Hint: A file named "index.js" allows [treating an entire directory as a single module](https://nodejs.org/api/modules.html#modules_folders_as_modules).) An example for this can be found [here](${doc:snippets}/resources/index.ts).
 
 > Note: You don't need to follow this exact layout of course, but it is the assumed configuration used in all examples below.
 
diff --git a/doc/w3c-api.md b/doc/w3c-api.md
diff --git a/tools/README.md b/tools/README.md
diff --git a/tools/generate-doc.ts b/tools/generate-doc.ts

Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@`
`20`	`20`	`]`
`21`	`21`	`},`
`22`	`22`	`"namespace": false,`
`23`		- "description": "This widget is expected by [`ListView`](./ListView.md) as a child (in JSX) or turn value of `createCell`. It's data-binding enabled by default. It's children can also [not be selected](../selector.md#encapsulation) from the outside, except for using `apply` directly on the instance. This allows using it as a function component as demonstrated in [this example](https://github.com/eclipsesource/tabris-decorators/tree/v${doc:moduleversion}/examples/listview-cells-js).",
	`23`	+ "description": "This widget is expected by [`ListView`](./ListView.md) as a child (in JSX) or turn value of `createCell`. It's data-binding enabled by default. It's children can also [not be selected](../selector.md#encapsulation) from the outside, except for using `apply` directly on the instance. This allows using it as a function component as demonstrated in [this example](${doc:listview-cells-js}).",
`24`	`24`	`"properties": {`
`25`	`25`	`"item": {`
`26`	`26`	`"type": "ItemType",`
Original file line number	Diff line number	Diff line change
`@@ -16,11 +16,11 @@`
`16`	`16`	`},`
`17`	`17`	`{`
`18`	`18`	`"title": "Defining raw color resource data in a separate JSON file.",`
`19`		`- "path": "https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/snippets/resources/colors.json"`
	`19`	`+ "path": "${doc:snippetsUrl}/resources/colors.json"`
`20`	`20`	`},`
`21`	`21`	`{`
`22`	`22`	"title": "Converting raw color resource data to `ColorResources` instance.",
`23`		`- "path": "https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/snippets/resources/index.ts"`
	`23`	`+ "path": "${doc:snippetsUrl}/resources/index.ts"`
`24`	`24`	`},`
`25`	`25`	`{`
`26`	`26`	`"title": "Using a ColorResources dictionary",`
`@@ -76,7 +76,7 @@`
`76`	`76`	`{`
`77`	`77`	`"name": "data",`
`78`	`78`	`"type": "Data",`
`79`		`- "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js colors JSON schema](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/schema/colors.json)."`
	`79`	`+ "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js colors JSON schema](${doc:colors.json})."`
`80`	`80`	`}`
`81`	`81`	`],`
`82`	`82`	`"returns": "ColorResources",`
`@@ -105,7 +105,7 @@`
`105`	`105`	`{`
`106`	`106`	`"name": "data",`
`107`	`107`	`"type": "Data",`
`108`		`- "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js colors JSON schema](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/schema/colors.json)."`
	`108`	`+ "description": "The raw data (plain object) to create the dictionary from. The format must match the [Tabris.js colors JSON schema](${doc:colors.json})."`
`109`	`109`	`}`
`110`	`110`	`],`
`111`	`111`	`"returns": "ColorResources",`
`@@ -116,7 +116,7 @@`
`116`	`116`	`"keyof Data"`
`117`	`117`	`]`
`118`	`118`	`},`
`119`		`- "description": "Creates a colors dictionary from the given raw \"data\" object. The format must match the [Tabris.js colors JSON schema](https://github.com/eclipsesource/tabris-js/blob/v${doc:moduleversion}/schema/colors.json). Entries in the \"data\" object starting with \"$\" are considered configuration options and will not become entries in the final colors dictionary."`
	`119`	`+ "description": "Creates a colors dictionary from the given raw \"data\" object. The format must match the [Tabris.js colors JSON schema](${doc:colors.json}). Entries in the \"data\" object starting with \"$\" are considered configuration options and will not become entries in the final colors dictionary."`
`120`	`120`	`}`
`121`	`121`	`]`
`122`	`122`	`}`