Skip to content

Commit 8ee7b71

Browse files
authored
Merge pull request #125 from Dataport/fix/swiss-cheese-documentation
Add meaningful additions to the documentation
2 parents 9fb20c7 + 3f8027e commit 8ee7b71

File tree

6 files changed

+43
-10
lines changed

6 files changed

+43
-10
lines changed

packages/clients/afm/API.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
This is a default compilation of POLAR feature packages for online services. This document and its child documents describe the setup.
44

5+
For all additional details, check the [full documentation](https://dataport.github.io/polar/docs/afm/client-afm.html).
6+
57
## Requirements
68

79
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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ For all additional details, check the [full documentation](https://dataport.gith
66

77
For the development test deployments and example configurations, [see here](https://dataport.github.io/polar#plugin-gallery).
88

9+
For a minimum working example, [see here](https://github.com/dopenguin/polar-fossgis-2024).
10+
911
## Basic usage
1012

1113
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.
1517
| fieldName | type | description |
1618
| - | - | - |
1719
| containerId | string | ID of the container the map is supposed to render itself to. |
18-
| 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). |
19-
| mapConfiguration | object | See full documentation for all possible configuration options. |
20+
| 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`. |
21+
| mapConfiguration | object | See [documentation of `@polar/core`](https://dataport.github.io/polar/docs/generic/core.html) for all possible configuration options. |
2022
| 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. |
2123
| 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. |
2224

packages/clients/snowbox/API.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,5 @@
33
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.
44

55
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.
6+
7+
For all additional details, check the [full documentation](https://dataport.github.io/polar/docs/snowbox/client-snowbox.html).

packages/plugins/Pins/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ The usage of `displayComponent` has no influence on the creation of Pins on the
1717
| appearOnClick | appearOnClick | Pin restrictions. See object description below. |
1818
| 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. |
1919
| style | style? | Display style configuration. |
20-
| initial | number[]? | Configuration options for setting an initial pin. |
20+
| initial | initial? | Configuration options for setting an initial pin. |
2121
| 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. |
2222
| 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'`. |
2323
| 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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,8 @@ <h3>Usage pattern</h3>
133133
</li>
134134
<li>
135135
Startup code. This is mostly putting the aforementioned parts together and adding configuration and subscriptions.
136+
<br/>
137+
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>.
136138
<pre><code>
137139
import client from '@polar/client-generic'
138140

scripts/makeDocs.js

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,29 @@ function toHtml(filePath, children) {
8484
</html>`
8585
}
8686

87+
/**
88+
* Removes documentation page link from documentation page; it's only relevant
89+
* when reading the API.md directly, not on this page.
90+
* @param {string} html the html'd API.md
91+
* @returns {string} html without the link to itself
92+
*/
93+
const filter = (html) => {
94+
const filterRegex =
95+
/<p>For all additional details, check the <a href=".*">full documentation<\/a>.<\/p>/g
96+
97+
const matches = (html.match(filterRegex) || []).length
98+
99+
if (matches !== 1) {
100+
console.error(html)
101+
102+
throw new Error(
103+
`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.`
104+
)
105+
}
106+
107+
return html.replace(filterRegex, '')
108+
}
109+
87110
const getDistinguishingFileNameFromPath = (path) => path.split('/').slice(-1)[0]
88111

89112
const dependencyPaths = fs
@@ -99,13 +122,15 @@ fs.readdirSync(docPath).forEach((f) => fs.rmSync(`${docPath}/${f}`))
99122
;[clientPath, ...dependencyPaths].forEach((path) => {
100123
const isMain = path === clientPath
101124
const markdownFile = `${path}/${isMain ? 'API.md' : 'README.md'}`
102-
const html = toHtml(
103-
markdownFile,
104-
isMain
105-
? dependencyPaths.map(
106-
(path) => getDistinguishingFileNameFromPath(path) + '.html'
107-
)
108-
: null
125+
const html = (isMain ? filter : (x) => x)(
126+
toHtml(
127+
markdownFile,
128+
isMain
129+
? dependencyPaths.map(
130+
(path) => getDistinguishingFileNameFromPath(path) + '.html'
131+
)
132+
: null
133+
)
109134
)
110135
const targetName = `${
111136
path === clientPath ? 'client-' : ''

0 commit comments

Comments
 (0)