Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doc: switch to mdbook
Browse files Browse the repository at this point in the history
Fixes #569.
tkurki committed Apr 9, 2022
1 parent e36eb26 commit eedcfc0
Showing 40 changed files with 67 additions and 57 deletions.
5 changes: 3 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -36,9 +36,10 @@ thumbs.db
.vscode

#Generated by publishing docs
gitbook-docs/otherBranches.md
gitbook-docs/vesselsBranch.md
mdbook/src/otherBranches.md
mdbook/src/vesselsBranch.md

#Generated
src/keyswithmetadata.json
mdbook/[0-9]*
dist
2 changes: 1 addition & 1 deletion .npmignore
Original file line number Diff line number Diff line change
@@ -39,4 +39,4 @@ thumbs.db
.vscode

#Gitbook source files, original and generated
gitbook-docs
mdbook
1 change: 0 additions & 1 deletion gitbook-docs/.gitignore

This file was deleted.

1 change: 0 additions & 1 deletion gitbook-docs/.npmignore

This file was deleted.

4 changes: 0 additions & 4 deletions gitbook-docs/book.json

This file was deleted.

3 changes: 3 additions & 0 deletions mdbook/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
book
otherBranches.md
vesselsBranch.md
5 changes: 5 additions & 0 deletions mdbook/book.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
[book]
authors = []
language = "en"
multilingual = false
src = "src"
17 changes: 17 additions & 0 deletions mdbook/docker-compose.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
version: '3'

services:
mdbook:
container_name: mdbook
image: peaceiris/mdbook:v0.4.13
stdin_open: true
tty: true
ports:
- 3000:3000
- 3001:3001
volumes:
- ${PWD}/mdbook:/book
command:
- serve
- --hostname
- '0.0.0.0'
7 changes: 1 addition & 6 deletions gitbook-docs/README.md → mdbook/src/README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,7 @@
# Introduction

This is the documentation for the [Signal K Specification](https://github.com/signalk/specification) _version_
version, which is available in the following formats;

* [html](http://signalk.org/specification/_version_/doc/) (this document) _version_
* [pdf](http://signalk.org/specification/_version_/doc/signalk.pdf)
* [epub](http://signalk.org/specification/_version_/doc/signalk.epub)
* [mobi](http://signalk.org/specification/_version_/doc/signalk.mobi)
version ([permalink](http://signalk.org/specification/_version_/doc/)).

## What is Signal K?

2 changes: 1 addition & 1 deletion gitbook-docs/SUMMARY.md → mdbook/src/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Signal K Specification

* [Signal K Specification](README.md)
* Getting Started
* [Getting Started]()
* [Using SK](start_using.md)
* [Developing with SK](start_developing.md)
* [Data Model]()
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
10 changes: 5 additions & 5 deletions gitbook-docs/data_model.md → mdbook/src/data_model.md
Original file line number Diff line number Diff line change
@@ -10,7 +10,7 @@ transmitted as UTF-8 JSON.
The full format is conceptually the simplest representation of data in Signal K. It contains all of the data from a
Signal K node, which in the case of a Signal K server could be many hundreds of data points.

[>]: # (mdpInsert ```json fsnip ../samples/full/docs-data_model.json)
[>]: # (mdpInsert ```json fsnip ../../samples/full/docs-data_model.json)
```json
{
"version": "1.0.0",
@@ -150,7 +150,7 @@ Signal K deltas as independent packets of data, much the same way as it would ha

An example delta message is presented below.

[>]: # (mdpInsert ```json fsnip ../samples/delta/docs-data_model.json --delKeys $..updates[2] --delKeys $..updates[1])
[>]: # (mdpInsert ```json fsnip ../../samples/delta/docs-data_model.json --delKeys $..updates[2] --delKeys $..updates[1])
```json
{
"context": "vessels.urn:mrn:imo:mmsi:234567890",
@@ -180,7 +180,7 @@ An example delta message is presented below.
[<]: #
The top level of a delta message contains an `updates` property and an optional `context` property.

[>]: # (mdpInsert ```json fsnip ../samples/delta/docs-data_model.json --ellipsify updates)
[>]: # (mdpInsert ```json fsnip ../../samples/delta/docs-data_model.json --ellipsify updates)
```json
{
"context": "vessels.urn:mrn:imo:mmsi:234567890",
@@ -199,7 +199,7 @@ a vessel directly under `vessels`. The delimiter in the context path is `.` (per
The `updates` property holds a JSON array of update objects, each of which may have a `source` property, a `timestamp`
property and an array of `values` containing one or more value objects.

[>]: # (mdpInsert ```json fsnip ../samples/delta/docs-data_model.json --snip $..updates[1])
[>]: # (mdpInsert ```json fsnip ../../samples/delta/docs-data_model.json --snip $..updates[1])
```json
{
"source": {
@@ -243,7 +243,7 @@ the delta stream, for example when received in AIS transmission. In this case th
full model, starting from the vessel's root, with just the relevant parts, and the path must be empty, indicating that
the value should be merged to the full model mounted where the delta‘s context property points:

[>]: # (mdpInsert ```json fsnip ../samples/delta/docs-data_model.json --delKeys $..updates[1] --delKeys $..updates[0] --ellipsify source --prettify 2 20)
[>]: # (mdpInsert ```json fsnip ../../samples/delta/docs-data_model.json --delKeys $..updates[1] --delKeys $..updates[0] --ellipsify source --prettify 2 20)
```json
{
"context": "vessels.urn:mrn:imo:mmsi:234567890",
Original file line number Diff line number Diff line change
@@ -17,7 +17,7 @@ saves time and prevents costly or even disastrous mistakes from occurring due to

The `meta` object exists at the same level as `value` and `$source` in each key in the Signal K data model.

[>]: # (mdpInsert ```json fsnip ../samples/full/docs-data_model_metadata.json --snip meta --prettify 2 85)
[>]: # (mdpInsert ```json fsnip ../../samples/full/docs-data_model_metadata.json --snip meta --prettify 2 85)
```json
{
"displayName": "Port Tachometer",
Original file line number Diff line number Diff line change
@@ -47,7 +47,7 @@ it is referenced by the `$source` property.
The first source of a particular data point becomes the default source for that data and a normal Signal K object is
created.

[>]: # (mdpInsert ```json fsnip ../samples/full/docs-data_model_multiple_values.json --delKeys sources values)
[>]: # (mdpInsert ```json fsnip ../../samples/full/docs-data_model_multiple_values.json --delKeys sources values)
```json
{
"self": "urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
@@ -72,7 +72,7 @@ It has come from device `sources.ttyUSB0.GP`, where further details can be found
If another value with different source arrives, the Signal K server will add the `values` attribute with values from
both the first and second sources. The initial source‘s data will continue to populate the `value` property in the key.

[>]: # (mdpInsert ```json fsnip ../samples/full/docs-data_model_multiple_values.json)
[>]: # (mdpInsert ```json fsnip ../../samples/full/docs-data_model_multiple_values.json)
```json
{
"self": "urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
@@ -127,7 +127,7 @@ both the first and second sources. The initial source‘s data will continue to
When a client subscribes to `navigation.courseOverGroundTrue`, they receive _all_ the values held. The update message
does not include the `values` path, the case above looks like:

[>]: # (mdpInsert ```json fsnip ../samples/delta/docs-data_model_multiple_values.json)
[>]: # (mdpInsert ```json fsnip ../../samples/delta/docs-data_model_multiple_values.json)
```json
{
"context": "vessels.urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
File renamed without changes.
File renamed without changes
4 changes: 2 additions & 2 deletions gitbook-docs/get.md → mdbook/src/get.md
Original file line number Diff line number Diff line change
@@ -17,7 +17,7 @@ GET http://localhost:3000/signalk/v1/api/vessels/self/steering/autopilot/target/

### Via a Delta

[>]: # (mdpInsert ```json fsnip ../data/get-valid/delta-get-array.json)
[>]: # (mdpInsert ```json fsnip ../../test/data/get-valid/delta-get-array.json)
```json
{
"context": "vessels.urn:mrn:signalk:uuid:6b0e776f-811a-4b35-980e-b93405371bc5",
@@ -35,7 +35,7 @@ The `context` key is optional, and defaults to `vessels.self`, which is the usua
The above GET request (v1) uses an array to allow multiple keys in a single GET. This is deprecated and strongly discouraged as it cannot work via http.
An alternative format has been added to the v1 specification where the GET request is:

[>]: # (mdpInsert ```json fsnip ../data/get-valid/delta-get-no-array.json)
[>]: # (mdpInsert ```json fsnip ../../test/data/get-valid/delta-get-no-array.json)
```json
{
"context": "vessels.urn:mrn:signalk:uuid:6b0e776f-811a-4b35-980e-b93405371bc5",
File renamed without changes.
File renamed without changes.
12 changes: 6 additions & 6 deletions gitbook-docs/notifications.md → mdbook/src/notifications.md
Original file line number Diff line number Diff line change
@@ -32,7 +32,7 @@ The alarm is : `vessels.self.notifications.navigation.anchor.currentRadius`

The alarm object is

[>]: # (mdpInsert ``` fsnip ../samples/full/docs-notifications.json --snip currentRadius --ellipsify timestamp "'$..['\$source']'")
[>]: # (mdpInsert ``` fsnip ../../samples/full/docs-notifications.json --snip currentRadius --ellipsify timestamp "'$..['\$source']'")
```
{
"value": {
@@ -65,7 +65,7 @@ In the case of an emergency, create a unique key: The alarm is : `vessels.[uuid]

The alarm object is

[>]: # (mdpInsert ``` fsnip ../samples/full/docs-notifications.json --snip mob --ellipsify $ ~value)
[>]: # (mdpInsert ``` fsnip ../../samples/full/docs-notifications.json --snip mob --ellipsify $ ~value)
```
{
"value": {
@@ -85,7 +85,7 @@ eg In the case of an alert, create a unique key by generating a path: The alarm

The alarm object is

[>]: # (mdpInsert ``` fsnip ../samples/full/docs-notifications.json --snip gnss --ellipsify $ ~value)
[>]: # (mdpInsert ``` fsnip ../../samples/full/docs-notifications.json --snip gnss --ellipsify $ ~value)
```
{
"value": {
@@ -113,7 +113,7 @@ Some alarms are especially important, eg MOB. This is a list of keys for special

An example to send an MOB alarm from an N2K source, the gateway would convert and send something like:

[>]: # (mdpInsert ``` fsnip ../samples/delta/docs-notifications.json --delKeys $.updates[1] --ellipsify source)
[>]: # (mdpInsert ``` fsnip ../../samples/delta/docs-notifications.json --delKeys $.updates[1] --ellipsify source)
```
{
"context": "vessels.urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
@@ -138,7 +138,7 @@ An example to send an MOB alarm from an N2K source, the gateway would convert an
[<]: #
The resulting full signalk tree would be:

[>]: # (mdpInsert ``` fsnip ../samples/full/docs-notifications.json --ellipsify $ ~vessels --delKeys navigation --ellipsify uuid "'$..['\$source']'")
[>]: # (mdpInsert ``` fsnip ../../samples/full/docs-notifications.json --ellipsify $ ~vessels --delKeys navigation --ellipsify uuid "'$..['\$source']'")
```
{
"vessels": {
@@ -163,7 +163,7 @@ The resulting full signalk tree would be:
[<]: #
To clear the alarm condition, send:

[>]: # (mdpInsert ``` fsnip ../samples/delta/docs-notifications.json --delKeys $.updates[0] --ellipsify source)
[>]: # (mdpInsert ``` fsnip ../../samples/delta/docs-notifications.json --delKeys $.updates[0] --ellipsify source)
```
{
"context": "vessels.urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
4 changes: 2 additions & 2 deletions gitbook-docs/put.md → mdbook/src/put.md
Original file line number Diff line number Diff line change
@@ -24,7 +24,7 @@ PUT http://localhost:3000/signalk/v1/api/vessels/self/steering/autopilot/target/

### Via a Delta

[>]: # (mdpInsert ```json fsnip ../test/data/put-valid/delta-put-array.json)
[>]: # (mdpInsert ```json fsnip ../../test/data/put-valid/delta-put-array.json)
```json
{
"context": "vessels.urn:mrn:signalk:uuid:6b0e776f-811a-4b35-980e-b93405371bc5",
@@ -43,7 +43,7 @@ The `context` key is optional, and defaults to `vessels.self`, which is the usua
The above PUT request (v1) uses an array to allow multiple keys in a single PUT. This is deprecated and strongly discouraged as it causes complex problems
with the request/response semantics in cases of partial failures. An alternative format has been added to the v1 specification where the PUT request is:

[>]: # (mdpInsert ```json fsnip ../test/data/put-valid/delta-put-no-array.json)
[>]: # (mdpInsert ```json fsnip ../../test/data/put-valid/delta-put-no-array.json)
```json
{
"context": "vessels.urn:mrn:signalk:uuid:6b0e776f-811a-4b35-980e-b93405371bc5",
File renamed without changes.
2 changes: 1 addition & 1 deletion gitbook-docs/rest_api.md → mdbook/src/rest_api.md
Original file line number Diff line number Diff line change
@@ -11,7 +11,7 @@ A Signal K server implementing the HTTP API may support http/2.
Making a `GET` request to `/signalk` returns a JSON object which specifies the available Signal K endpoints and some
information about the server. Also see [versioning](versioning.md) for details about `version` strings.

[>]: # (mdpInsert ```json fsnip ../samples/discovery/docs-rest_api.json)
[>]: # (mdpInsert ```json fsnip ../../samples/discovery/docs-rest_api.json)
```json
{
"endpoints": {
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
4 changes: 2 additions & 2 deletions gitbook-docs/streaming_api.md → mdbook/src/streaming_api.md
Original file line number Diff line number Diff line change
@@ -24,7 +24,7 @@ See [Subscription Protocol](subscription_protocol.md) for more details.

Upon connection the server MUST send a 'hello' JSON message, for example:

[>]: # (mdpInsert ```json cat ../samples/hello/docs-hello.json)
[>]: # (mdpInsert ```json cat ../../samples/hello/docs-hello.json)
```json
{
"name": "foobar marine server",
@@ -65,7 +65,7 @@ The playback api is located at `/signalk/v1/playback`. An example url for histor

The hello message for a history playback stream MUST NOT contain the `timestamp` property and MUST include the properties `startTime` and `playbackRate`. The delta stream format for history playback is the normal streaming format. Timestamps indicate the time data was originally captured.

[>]: # (mdpInsert ```json cat ../samples/hello/docs-hello-playback.json)
[>]: # (mdpInsert ```json cat ../../samples/hello/docs-hello-playback.json)
```json
{
"name": "foobar marine server",
Original file line number Diff line number Diff line change
@@ -6,7 +6,7 @@ By default a Signal K server will provide a new WebSocket client with a delta st
updates are received from sources. E.g. `/signalk/v1/stream` will provide the following delta stream, every time the
log value changes.

[>]: # (mdpInsert ```json fsnip ../samples/delta/docs-subscription_protocol.json)
[>]: # (mdpInsert ```json fsnip ../../samples/delta/docs-subscription_protocol.json)
```json
{
"context": "vessels.urn:mrn:imo:mmsi:234567890",
@@ -45,7 +45,7 @@ First you will want to unsubscribe from the current default (or you may have alr
`ws://hostname/signalk/v1/stream?subscribe=none`). To unsubscribe all create an `unsubscribe` message with wildcards
and send the message over the WebSocket connection:

[>]: # (mdpInsert ```json fsnip ../samples/unsubscribe/docs-subscription_protocol.json --prettify 2 20)
[>]: # (mdpInsert ```json fsnip ../../samples/unsubscribe/docs-subscription_protocol.json --prettify 2 20)
```json
{
"context": "*",
@@ -57,7 +57,7 @@ and send the message over the WebSocket connection:
[<]: #
To subscribe to the required criteria send a suitable subscribe message:

[>]: # (mdpInsert ```json fsnip ../samples/subscribe/docs-subscription_protocol1.json --prettify)
[>]: # (mdpInsert ```json fsnip ../../samples/subscribe/docs-subscription_protocol1.json --prettify)
```json
{
"context": "vessels.self",
@@ -132,7 +132,7 @@ wants those items for the self vessel.

This can be achieved by a default WebSocket connection `/signalk/v1/stream?subcribe=none`, then sending a JSON message:

[>]: # (mdpInsert ```json fsnip ../samples/subscribe/docs-subscription_protocol2.json --prettify)
[>]: # (mdpInsert ```json fsnip ../../samples/subscribe/docs-subscription_protocol2.json --prettify)
```json
{
"context": "vessels.self",
@@ -150,7 +150,7 @@ subscription method.

### Map display with all known vessel positions & directions, served over 3G cellular connection

[>]: # (mdpInsert ```json fsnip ../samples/subscribe/docs-subscription_protocol3.json --prettify)
[>]: # (mdpInsert ```json fsnip ../../samples/subscribe/docs-subscription_protocol3.json --prettify)
```json
{
"context": "vessels.*",
@@ -174,7 +174,7 @@ vessels, sent every 2 minutes (120 seconds) even if no data has been updated.

### Position of a certain vessel, immediately it changes, but once per minute at most

[>]: # (mdpInsert ```json fsnip ../samples/subscribe/docs-subscription_protocol4.json --prettify)
[>]: # (mdpInsert ```json fsnip ../../samples/subscribe/docs-subscription_protocol4.json --prettify)
```json
{
"context": "vessels.230029970",
File renamed without changes.
File renamed without changes.
15 changes: 5 additions & 10 deletions package.json
Original file line number Diff line number Diff line change
@@ -10,16 +10,12 @@
"js:dist": "babel src --out-dir dist --copy-files",
"schema:version": "cross-var replace-in-file /https:\\\\/\\\\/signalk.org\\\\/specification\\\\/[\\\\w\\\\.]+\\\\/schemas\\\\//g https://signalk.org/specification/$npm_package_version/schemas/ './**/*.j*' --ignore=./package.json,./node_modules/** --isRegex --verbose",
"schema:publish": "git checkout gh-pages && git checkout master -- schemas && cross-var mkdir $npm_package_version && cross-var git add $npm_package_version && cross-var git mv schemas/ $npm_package_version/ && git commit -m \"Schemas from master\" && git push",
"docs:changelog": "github-changes -f gitbook-docs/changelog.md -o signalk -r specification -a --only-pulls --use-commit-body --data=pulls",
"docs:prep": "gitbook install gitbook-docs && cross-var replace-in-file /_version_/g $npm_package_version ./gitbook-docs/* --isRegex --verbose && mdprepare gitbook-docs/*.md",
"docs:prep": "cross-var replace-in-file /_version_/g $npm_package_version ./mdbook/src/* --isRegex --verbose && mdprepare mdbook/src/*.md",
"docs:keys": "node scripts/processSchemaFiles.js",
"docs:html": "cross-var gitbook build gitbook-docs $npm_package_version/doc",
"docs:pdf": "cross-var gitbook pdf gitbook-docs $npm_package_version/doc/signalk.pdf",
"docs:mobi": "cross-var gitbook mobi gitbook-docs $npm_package_version/doc/signalk.mobi",
"docs:epub": "cross-var gitbook pdf gitbook-docs $npm_package_version/doc/signalk.epub",
"docs:serve": "gitbook serve gitbook-docs",
"docs:all": "npm run docs:prep && npm run docs:changelog && npm run docs:keys && npm run docs:html && npm run docs:pdf && npm run docs:mobi && npm run docs:epub",
"docs:publish": "npm run docs:all && cross-var git add $npm_package_version && git stash && git checkout gh-pages && git pull && cross-var git checkout stash -- $npm_package_version && git add master && cross-var git commit --allow-empty -m $npm_package_version && git push git@github.com:signalk/specification gh-pages"
"docs:html": "cross-var docker-compose -f mdbook/docker-compose.yml run mdbook build -d $npm_package_version",
"docs:serve": "docker-compose -f mdbook/docker-compose.yml up",
"docs:all": "npm run docs:prep && npm run docs:keys && npm run docs:html",
"docs:publish-local-gh-pages": "npm run docs:all && mv mdbook/$npm_package_version . && cross-var git add $npm_package_version && git stash && git checkout gh-pages && git pull && cross-var git checkout stash -- $npm_package_version && git add master && cross-var git commit --allow-empty -m $npm_package_version"
},
"repository": {
"type": "git",
@@ -56,7 +52,6 @@
"chai": "^1.9.2",
"cross-var": "1.1.0",
"fsnip": "^0.9.5",
"gitbook-cli": "^2.3.0",
"github-changes": "^1.0.4",
"infuse.js": "^2.0.2",
"markdown-it": "^8.0.0",
6 changes: 3 additions & 3 deletions scripts/processSchemaFiles.js
Original file line number Diff line number Diff line change
@@ -344,8 +344,8 @@ class Parser {
})

fs.writeFileSync(path.join(__dirname, '../src/keyswithmetadata.json'), JSON.stringify(keysWithMeta, null, 2))
fs.writeFileSync(path.join(__dirname, '../gitbook-docs/vesselsBranch.md'), vesselsDoc)
fs.writeFileSync(path.join(__dirname, '../gitbook-docs/otherBranches.md'), othersDoc)
fs.writeFileSync(path.join(__dirname, '../mdbook/src/vesselsBranch.md'), vesselsDoc)
fs.writeFileSync(path.join(__dirname, '../mdbook/src/otherBranches.md'), othersDoc)
})

/*
@@ -590,5 +590,5 @@ class Parser {
new Parser({
definitions: './schemas/definitions.json',
entry: './schemas/signalk.json',
output: './gitbook-docs/keys'
output: './mdbook/src/keys'
})

0 comments on commit eedcfc0

Please sign in to comment.