From 6beec58d0149b975686ce0efa89ecd31e579d817 Mon Sep 17 00:00:00 2001 From: Teppo Kurki Date: Sun, 31 Oct 2021 17:17:56 +0200 Subject: [PATCH] doc: switch to mdbook Fixes #569. --- .gitignore | 5 +++-- .npmignore | 2 +- gitbook-docs/.gitignore | 1 - gitbook-docs/.npmignore | 1 - gitbook-docs/book.json | 4 ---- mdbook/.gitignore | 3 +++ mdbook/book.toml | 5 +++++ mdbook/docker-compose.yml | 18 ++++++++++++++++++ {gitbook-docs => mdbook/src}/README.md | 7 +------ {gitbook-docs => mdbook/src}/SUMMARY.md | 2 +- .../src}/access_requests.md | 0 {gitbook-docs => mdbook/src}/apps_api.md | 0 {gitbook-docs => mdbook/src}/changelog.md | 0 {gitbook-docs => mdbook/src}/connection.md | 0 .../src}/consumer_discovery_process.dia | Bin .../src}/consumer_discovery_process.png | Bin {gitbook-docs => mdbook/src}/data_model.md | 0 .../src}/data_model_metadata.md | 0 .../src}/data_model_multiple_values.md | 0 .../src}/gateway_and_server.dia | Bin .../src}/gateway_and_server.png | Bin {gitbook-docs => mdbook/src}/get.md | 0 {gitbook-docs => mdbook/src}/how_to_help.md | 0 {gitbook-docs => mdbook/src}/keys.md | 0 {gitbook-docs => mdbook/src}/notifications.md | 0 {gitbook-docs => mdbook/src}/put.md | 0 .../src}/request_response.md | 0 {gitbook-docs => mdbook/src}/rest_api.md | 0 {gitbook-docs => mdbook/src}/security.md | 0 {gitbook-docs => mdbook/src}/server_only.dia | Bin {gitbook-docs => mdbook/src}/server_only.png | Bin {gitbook-docs => mdbook/src}/sources.md | 0 .../src}/start_developing.md | 0 {gitbook-docs => mdbook/src}/start_using.md | 0 {gitbook-docs => mdbook/src}/streaming_api.md | 0 .../src}/subscription_protocol.md | 0 {gitbook-docs => mdbook/src}/urls_ports.md | 0 {gitbook-docs => mdbook/src}/versioning.md | 0 package.json | 14 +++++--------- scripts/processSchemaFiles.js | 4 ++-- 40 files changed, 39 insertions(+), 27 deletions(-) delete mode 100644 gitbook-docs/.gitignore delete mode 100644 gitbook-docs/.npmignore delete mode 100644 gitbook-docs/book.json create mode 100644 mdbook/.gitignore create mode 100644 mdbook/book.toml create mode 100644 mdbook/docker-compose.yml rename {gitbook-docs => mdbook/src}/README.md (93%) rename {gitbook-docs => mdbook/src}/SUMMARY.md (97%) rename {gitbook-docs => mdbook/src}/access_requests.md (100%) rename {gitbook-docs => mdbook/src}/apps_api.md (100%) rename {gitbook-docs => mdbook/src}/changelog.md (100%) rename {gitbook-docs => mdbook/src}/connection.md (100%) rename {gitbook-docs => mdbook/src}/consumer_discovery_process.dia (100%) rename {gitbook-docs => mdbook/src}/consumer_discovery_process.png (100%) rename {gitbook-docs => mdbook/src}/data_model.md (100%) rename {gitbook-docs => mdbook/src}/data_model_metadata.md (100%) rename {gitbook-docs => mdbook/src}/data_model_multiple_values.md (100%) rename {gitbook-docs => mdbook/src}/gateway_and_server.dia (100%) rename {gitbook-docs => mdbook/src}/gateway_and_server.png (100%) rename {gitbook-docs => mdbook/src}/get.md (100%) rename {gitbook-docs => mdbook/src}/how_to_help.md (100%) rename {gitbook-docs => mdbook/src}/keys.md (100%) rename {gitbook-docs => mdbook/src}/notifications.md (100%) rename {gitbook-docs => mdbook/src}/put.md (100%) rename {gitbook-docs => mdbook/src}/request_response.md (100%) rename {gitbook-docs => mdbook/src}/rest_api.md (100%) rename {gitbook-docs => mdbook/src}/security.md (100%) rename {gitbook-docs => mdbook/src}/server_only.dia (100%) rename {gitbook-docs => mdbook/src}/server_only.png (100%) rename {gitbook-docs => mdbook/src}/sources.md (100%) rename {gitbook-docs => mdbook/src}/start_developing.md (100%) rename {gitbook-docs => mdbook/src}/start_using.md (100%) rename {gitbook-docs => mdbook/src}/streaming_api.md (100%) rename {gitbook-docs => mdbook/src}/subscription_protocol.md (100%) rename {gitbook-docs => mdbook/src}/urls_ports.md (100%) rename {gitbook-docs => mdbook/src}/versioning.md (100%) diff --git a/.gitignore b/.gitignore index 29f37c227..cdecaf5de 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/.npmignore b/.npmignore index 08d190449..1b95744ee 100644 --- a/.npmignore +++ b/.npmignore @@ -39,4 +39,4 @@ thumbs.db .vscode #Gitbook source files, original and generated -gitbook-docs +mdbook \ No newline at end of file diff --git a/gitbook-docs/.gitignore b/gitbook-docs/.gitignore deleted file mode 100644 index 09ea21bf7..000000000 --- a/gitbook-docs/.gitignore +++ /dev/null @@ -1 +0,0 @@ -_book/ diff --git a/gitbook-docs/.npmignore b/gitbook-docs/.npmignore deleted file mode 100644 index 09ea21bf7..000000000 --- a/gitbook-docs/.npmignore +++ /dev/null @@ -1 +0,0 @@ -_book/ diff --git a/gitbook-docs/book.json b/gitbook-docs/book.json deleted file mode 100644 index 3d30abf8a..000000000 --- a/gitbook-docs/book.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "title": "Signal K Documentation", - "plugins" : [ "anchors" ] -} diff --git a/mdbook/.gitignore b/mdbook/.gitignore new file mode 100644 index 000000000..939d092ba --- /dev/null +++ b/mdbook/.gitignore @@ -0,0 +1,3 @@ +book +otherBranches.md +vesselsBranch.md diff --git a/mdbook/book.toml b/mdbook/book.toml new file mode 100644 index 000000000..d34134a46 --- /dev/null +++ b/mdbook/book.toml @@ -0,0 +1,5 @@ +[book] +authors = [] +language = "en" +multilingual = false +src = "src" diff --git a/mdbook/docker-compose.yml b/mdbook/docker-compose.yml new file mode 100644 index 000000000..76df93df2 --- /dev/null +++ b/mdbook/docker-compose.yml @@ -0,0 +1,18 @@ +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}/gitbook-docs:/book + - ${PWD}/mdbook:/book + command: + - serve + - --hostname + - '0.0.0.0' \ No newline at end of file diff --git a/gitbook-docs/README.md b/mdbook/src/README.md similarity index 93% rename from gitbook-docs/README.md rename to mdbook/src/README.md index 553bf1eac..371858f5c 100644 --- a/gitbook-docs/README.md +++ b/mdbook/src/README.md @@ -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? diff --git a/gitbook-docs/SUMMARY.md b/mdbook/src/SUMMARY.md similarity index 97% rename from gitbook-docs/SUMMARY.md rename to mdbook/src/SUMMARY.md index 9778fe37d..c9b9ee0ac 100644 --- a/gitbook-docs/SUMMARY.md +++ b/mdbook/src/SUMMARY.md @@ -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]() diff --git a/gitbook-docs/access_requests.md b/mdbook/src/access_requests.md similarity index 100% rename from gitbook-docs/access_requests.md rename to mdbook/src/access_requests.md diff --git a/gitbook-docs/apps_api.md b/mdbook/src/apps_api.md similarity index 100% rename from gitbook-docs/apps_api.md rename to mdbook/src/apps_api.md diff --git a/gitbook-docs/changelog.md b/mdbook/src/changelog.md similarity index 100% rename from gitbook-docs/changelog.md rename to mdbook/src/changelog.md diff --git a/gitbook-docs/connection.md b/mdbook/src/connection.md similarity index 100% rename from gitbook-docs/connection.md rename to mdbook/src/connection.md diff --git a/gitbook-docs/consumer_discovery_process.dia b/mdbook/src/consumer_discovery_process.dia similarity index 100% rename from gitbook-docs/consumer_discovery_process.dia rename to mdbook/src/consumer_discovery_process.dia diff --git a/gitbook-docs/consumer_discovery_process.png b/mdbook/src/consumer_discovery_process.png similarity index 100% rename from gitbook-docs/consumer_discovery_process.png rename to mdbook/src/consumer_discovery_process.png diff --git a/gitbook-docs/data_model.md b/mdbook/src/data_model.md similarity index 100% rename from gitbook-docs/data_model.md rename to mdbook/src/data_model.md diff --git a/gitbook-docs/data_model_metadata.md b/mdbook/src/data_model_metadata.md similarity index 100% rename from gitbook-docs/data_model_metadata.md rename to mdbook/src/data_model_metadata.md diff --git a/gitbook-docs/data_model_multiple_values.md b/mdbook/src/data_model_multiple_values.md similarity index 100% rename from gitbook-docs/data_model_multiple_values.md rename to mdbook/src/data_model_multiple_values.md diff --git a/gitbook-docs/gateway_and_server.dia b/mdbook/src/gateway_and_server.dia similarity index 100% rename from gitbook-docs/gateway_and_server.dia rename to mdbook/src/gateway_and_server.dia diff --git a/gitbook-docs/gateway_and_server.png b/mdbook/src/gateway_and_server.png similarity index 100% rename from gitbook-docs/gateway_and_server.png rename to mdbook/src/gateway_and_server.png diff --git a/gitbook-docs/get.md b/mdbook/src/get.md similarity index 100% rename from gitbook-docs/get.md rename to mdbook/src/get.md diff --git a/gitbook-docs/how_to_help.md b/mdbook/src/how_to_help.md similarity index 100% rename from gitbook-docs/how_to_help.md rename to mdbook/src/how_to_help.md diff --git a/gitbook-docs/keys.md b/mdbook/src/keys.md similarity index 100% rename from gitbook-docs/keys.md rename to mdbook/src/keys.md diff --git a/gitbook-docs/notifications.md b/mdbook/src/notifications.md similarity index 100% rename from gitbook-docs/notifications.md rename to mdbook/src/notifications.md diff --git a/gitbook-docs/put.md b/mdbook/src/put.md similarity index 100% rename from gitbook-docs/put.md rename to mdbook/src/put.md diff --git a/gitbook-docs/request_response.md b/mdbook/src/request_response.md similarity index 100% rename from gitbook-docs/request_response.md rename to mdbook/src/request_response.md diff --git a/gitbook-docs/rest_api.md b/mdbook/src/rest_api.md similarity index 100% rename from gitbook-docs/rest_api.md rename to mdbook/src/rest_api.md diff --git a/gitbook-docs/security.md b/mdbook/src/security.md similarity index 100% rename from gitbook-docs/security.md rename to mdbook/src/security.md diff --git a/gitbook-docs/server_only.dia b/mdbook/src/server_only.dia similarity index 100% rename from gitbook-docs/server_only.dia rename to mdbook/src/server_only.dia diff --git a/gitbook-docs/server_only.png b/mdbook/src/server_only.png similarity index 100% rename from gitbook-docs/server_only.png rename to mdbook/src/server_only.png diff --git a/gitbook-docs/sources.md b/mdbook/src/sources.md similarity index 100% rename from gitbook-docs/sources.md rename to mdbook/src/sources.md diff --git a/gitbook-docs/start_developing.md b/mdbook/src/start_developing.md similarity index 100% rename from gitbook-docs/start_developing.md rename to mdbook/src/start_developing.md diff --git a/gitbook-docs/start_using.md b/mdbook/src/start_using.md similarity index 100% rename from gitbook-docs/start_using.md rename to mdbook/src/start_using.md diff --git a/gitbook-docs/streaming_api.md b/mdbook/src/streaming_api.md similarity index 100% rename from gitbook-docs/streaming_api.md rename to mdbook/src/streaming_api.md diff --git a/gitbook-docs/subscription_protocol.md b/mdbook/src/subscription_protocol.md similarity index 100% rename from gitbook-docs/subscription_protocol.md rename to mdbook/src/subscription_protocol.md diff --git a/gitbook-docs/urls_ports.md b/mdbook/src/urls_ports.md similarity index 100% rename from gitbook-docs/urls_ports.md rename to mdbook/src/urls_ports.md diff --git a/gitbook-docs/versioning.md b/mdbook/src/versioning.md similarity index 100% rename from gitbook-docs/versioning.md rename to mdbook/src/versioning.md diff --git a/package.json b/package.json index 4139ee925..9092974ec 100644 --- a/package.json +++ b/package.json @@ -11,15 +11,12 @@ "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/doc", + "docs:serve": "docker-compose -f mdbook/docker-compose.yml up", + "docs:all": "npm run docs:prep && npm run docs:changelog && npm run docs:keys && npm run docs:html", + "docs:publish": "TODO 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" }, "repository": { "type": "git", @@ -56,7 +53,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", diff --git a/scripts/processSchemaFiles.js b/scripts/processSchemaFiles.js index 8cdc0e3a2..975e713d3 100755 --- a/scripts/processSchemaFiles.js +++ b/scripts/processSchemaFiles.js @@ -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) }) /*