Merge pull request #125 from Dataport/fix/swiss-cheese-documentation

Add meaningful additions to the documentation

packages/clients/afm/API.md

@@ -2,6 +2,8 @@
 
 This is a default compilation of POLAR feature packages for online services. This document and its child documents describe the setup.
 
+For all additional details, check the [full documentation](https://dataport.github.io/polar/docs/afm/client-afm.html).
+
 ## Requirements
 
 To understand this document, programming knowledge (preferably in JavaScript) are required. This is a technical document describing how to integrate the map client with its programmatic API.

packages/clients/generic/API.md

@@ -6,6 +6,8 @@ For all additional details, check the [full documentation](https://dataport.gith
 
 For the development test deployments and example configurations, [see here](https://dataport.github.io/polar#plugin-gallery).
 
+For a minimum working example, [see here](https://github.com/dopenguin/polar-fossgis-2024).
+
 ## Basic usage
 
 The NPM package `@polar/client-generic` can be installed via NPM or downloaded from the [release page](https://github.com/Dataport/polar/releases). When using `import mapClient from '@polar/client-generic'`, the object `mapClient` contains a method `createMap`. This is the main method required to get the client up and running. Should you use another import method, check the package's `dist` folder for available files.
@@ -15,8 +17,8 @@ The method expects a single object with the following parameters.
 | fieldName | type | description |
 | - | - | - |
 | containerId | string | ID of the container the map is supposed to render itself to. |
-| services | object[] \| string | Either a link to a service registry or an array containing service description objects. For more details, see the startup section on [POLAR documentation](https://dataport.github.io/polar/documentation.html#configuration). |
-| mapConfiguration | object | See full documentation for all possible configuration options. |
+| services | object[] \| string | Either a link to a service registry or an array containing service description objects. For more details, see the startup section on [POLAR documentation](https://dataport.github.io/polar/documentation.html#configuration). This parameter can be seen as an accessible version of `mapConfiguration.layerConf`. |
+| mapConfiguration | object | See [documentation of `@polar/core`](https://dataport.github.io/polar/docs/generic/core.html) for all possible configuration options. |
 | enabledPlugins  | string[]? | This is a client-specific field. Since the `@polar/client-generic` client contains all existing plugins, they are activated by strings. The strings match their package names: `'address-search' \| 'attributions' \| 'draw'* \| 'export' \| 'filter'* \| 'fullscreen'* \| 'geo-location'* \| 'gfi'* \| 'icon-menu' \| 'layer-chooser'* \| 'legend' \| 'loading-indicator' \| 'pins' \| 'reverse-geocoder' \| 'scale' \| 'toast' \| 'zoom'*`. The plugins marked with * are nested in the `'icon-menu'` in this pre-layouting, hence they depend upon it being active, too. |
 | modifyLayerConfiguration | ((layerConf: object[]) => object[])? | Defaults to identity function. This function is applied to the loaded layer configuration before usage. That is, the `services` can be modified by this to e.g. set parameters not supported by the service register, add additional layers, and so on. |
 

packages/clients/snowbox/API.md

@@ -3,3 +3,5 @@
 This is an API file that is used as part of the generated documentation. It will appear as main document in the snowbox's documentation.
 
 If the snowbox implemented any own features that are not derived from either core of plugins, this would be the place to document them. However, since that's not the case, it only features this introduction text and the link list below.
+
+For all additional details, check the [full documentation](https://dataport.github.io/polar/docs/snowbox/client-snowbox.html).

packages/plugins/Pins/README.md

@@ -17,7 +17,7 @@ The usage of `displayComponent` has no influence on the creation of Pins on the
 | appearOnClick    | appearOnClick | Pin restrictions. See object description below.                                                                                                                                                                                                                                                     |
 | coordinateSource | string        | The pins plugin may react to changes in other plugins. This specifies the path to such store positions. The position must, when subscribed to, return a GeoJSON feature. Please mind that, when referencing another plugin, that plugin must be in `addPlugins` before this one. |
 | style            | style?        | Display style configuration.                                                                                                                                                                                                                                                                        |
-| initial          | number[]?                               | Configuration options for setting an initial pin.                                                                                                                                                                                                                                                   |
+| initial          | initial? | Configuration options for setting an initial pin.                                                                                                                                                                                                                                                   |
 | boundaryLayerId  | string?       | Id of a vector layer to restrict pins to. When pins are moved or created outside of the boundary, an information will be shown and the pin is reset to its previous state. The map will wait at most 10s for the layer to load; should it not happen, the geolocation feature is turned off.        |
 | boundaryOnError | ('strict' \| 'permissive')? | If the boundary layer check does not work due to loading or configuration errors, style `'strict'` will disable the pins feature, and style `'permissive'` will act as if no boundaryLayerId was set. Defaults to `'permissive'`. |
 | toastAction      | string?       | If `boundaryLayerId` is set, and the pin is moved or created outside the boundary, this string will be used as action to send a toast information to the user. If no toast information is desired, leave this field undefined; for testing purposes, you can still find information in the console. |

pages/documentation.html

@@ -133,6 +133,8 @@ <h3>Usage pattern</h3>
         </li>
         <li>
           Startup code. This is mostly putting the aforementioned parts together and adding configuration and subscriptions.
+          <br/>
+          For a minimum working example, checkout <a href="https://github.com/dopenguin/polar-fossgis-2024" target="_blank">this repository ↗</a> which includes the example shown in the <a href="https://dataport.github.io/polar/#media" target="_blank">FOSSGIS 2024 presentation ↗</a>.
           <pre><code>
 import client from '@polar/client-generic'
 

scripts/makeDocs.js

@@ -84,6 +84,29 @@ function toHtml(filePath, children) {
 </html>`
 }
 
+/**
+ * Removes documentation page link from documentation page; it's only relevant
+ * when reading the API.md directly, not on this page.
+ * @param {string} html the html'd API.md
+ * @returns {string} html without the link to itself
+ */
+const filter = (html) => {
+  const filterRegex =
+    /<p>For all additional details, check the <a href=".*">full documentation<\/a>.<\/p>/g
+
+  const matches = (html.match(filterRegex) || []).length
+
+  if (matches !== 1) {
+    console.error(html)
+
+    throw new Error(
+      `makeDocs.js expected to remove a self-reference in HTML generated from an API.md with exactly one match, but found ${matches} matches. This indicates an unexpected change in the API.md.`
+    )
+  }
+
+  return html.replace(filterRegex, '')
+}
+
 const getDistinguishingFileNameFromPath = (path) => path.split('/').slice(-1)[0]
 
 const dependencyPaths = fs
@@ -99,13 +122,15 @@ fs.readdirSync(docPath).forEach((f) => fs.rmSync(`${docPath}/${f}`))
 ;[clientPath, ...dependencyPaths].forEach((path) => {
   const isMain = path === clientPath
   const markdownFile = `${path}/${isMain ? 'API.md' : 'README.md'}`
-  const html = toHtml(
-    markdownFile,
-    isMain
-      ? dependencyPaths.map(
-          (path) => getDistinguishingFileNameFromPath(path) + '.html'
-        )
-      : null
+  const html = (isMain ? filter : (x) => x)(
+    toHtml(
+      markdownFile,
+      isMain
+        ? dependencyPaths.map(
+            (path) => getDistinguishingFileNameFromPath(path) + '.html'
+          )
+        : null
+    )
   )
   const targetName = `${
     path === clientPath ? 'client-' : ''