feat: Docker compose.yaml

.gitignore

@@ -17,3 +17,7 @@ docs
 *.pdf
 .idea
 cat
+
+# Website output
+_site
+.jekyll-cache

Development/Documentation.md

@@ -3,67 +3,30 @@
 ## Overview
 The documentation consists of three main parts.
 
-* The "Home Webgpage" of the project , describing the purpose and use cases for the software. The source is located at https://github.com/SciCatProject/scicatproject.github.io 
-* The documentation proper, split into User,Operator,Ingestor and Developer manual. The source is located at https://github.com/SciCatProject/documentation .  It covers all components of the software, i.e  frontend and backend. The documentation tool [honkit](https://honkit.netlify.app/) (successor of gitbook) is used.
-* The documentation of the REST API of the backend. This is generated from the swagger.json file, which itself is generated from the model descriptions in loopback
-
+* The "Home Webgpage" of the project , describing the purpose and use cases for the software. The source is located at https://github.com/SciCatProject/scicatproject.github.io
+* The documentation proper, split into User,Operator,Ingestor and Developer manual. The source is located at https://github.com/SciCatProject/documentation . It covers all components of the software, i.e  frontend and backend. The documentation tool [honkit](https://honkit.netlify.app/) (successor of gitbook) is used.
+* The documentation of the REST API of the backend. This is generated from the OpenAPI description, which itself is generated from the model descriptions in the backend code.
 
 All parts are hosted on the [GitHub Pages platform](https://pages.github.com/). The documentation part is "injected" into the GitHub pages automatically by a travis job, which runs after each commit to the documentation repository
 
 The live web site is then visible on the following URLs respectively
 * https://scicatproject.github.io/
 * https://scicatproject.github.io/documentation
-* https://scicatproject.github.io/api
+* The REST API not generated statically but is available from each running SciCat
+  backend (for example, the public [ESS instance](https://scicat.ess.eu/explorer)).
+  <!-- TODO update following completion of https://github.com/SciCatProject/documentation/issues/42 -->
 
 ## Changes and Deployment of Home Webpage
 
-```
-git clone https://github.com/SciCatProject/scicatproject.github.io`
-cd scicatproject.github.io
-
-# make your changes on index.html directly, then git add and git commit as usual
-
-git push origin master
-```
+The homepage is built using [Jekyll](https://jekyllrb.com/) and hosted on GitHub pages.
+The source is located in the repository
+[SciCatProject/scicatproject.github.io](https://github.com/SciCatProject/scicatproject.github.io).
 
-After pushing the changes they will immediately become visible at the URL https://scicatproject.github.io/
+After pushing the changes they will become visible at the URL https://scicatproject.github.io/
 
 ## Changes and Deployment of Manuals
 
-```
-git clone https://github.com/SciCatProject/documentation.git`
-cd documentation
-
-# make your edit/add/commit cycle
-
-npm install honkit --save
-npx honkit build
-```
-
-### Serving the Documentation locally
-
-`npx honkit serve --port 4040`
-
-### Publishing the documentation
-
-`git push origin master`
-
-The push to the origin repo will trigger a travis job, which will publish the resulting documentation to https://scicatproject.github.io/documentation
-
-## Changes and Deployment of API Documentation
-
-Use the following command to regenerate  the API with an up-to-date swagger.json file
-
-```
-    # to install redoc-cli:
-    # sudo npm install -g redoc-cli
-
-    # to get an updated swagger.json file
-    # wget https://YOUR-API-SERVER/explorer/swagger.json
-
-    redoc-cli bundle -o index.html swagger.json
-
-    # the make commit which replaces the index.html file at 
-    # https://github.com/SciCatProject/scicatproject.github.io/tree/master/api
-```
-
+Manuals are built using [honkit](https://honkit.netlify.app/) from the
+[SciCatProject/documentation](https://github.com/SciCatProject/documentation)
+repository. After pushing the changes they will become visible at the URL
+https://scicatproject.github.io/documentation.

README.md

@@ -9,7 +9,7 @@ See the [SciCat Home Webpage](https://scicatproject.github.io) for an overview o
 
 ## Structure of Documentation
 
-The documentaion is split into the following chapters:
+SciCat documentation is split into the following chapters:
 
 * [User Guide](Users) - Users of the system can come here to see screen captures, FAQs and find resources on how to better understand SciCat.
 * [Operator Guide](Operator) - System admins read this part to set up SciCat for their location
@@ -20,3 +20,29 @@ The documentaion is split into the following chapters:
 
 [SciCat Project: Data Catalog System (2017)](https://icatproject.org/wp-content/uploads/2017/12/ICAT_F2F_2017_PSI.pdf)
 [SciCat talk from Luke Gorman on Joint ExPaNDS and PaNOSC Meeting Feb 2020](https://indico.esss.lu.se/event/1373/contributions/10773/attachments/9761/15638/Lund2020.pdf)
+
+## Building
+
+Docs are built using [honkit](https://honkit.netlify.app/). This can either be installed locally using npm or run via docker.
+
+### Serving documentation with docker
+
+```
+docker compose up -d
+```
+
+This should start the honkit server on http://localhost:4040. Honkit will watch for changes in the source files and automatically re-build them.
+
+### Serving the Documentation locally
+
+You can also run the honkit server locally using npm:
+
+```
+npm install
+npm run start
+```
+
+## Publishing the documentation
+
+The [website](https://scicatproject.github.io/documentation) will be automatically
+rebuilt after each change to the `master` branch by a github action.

compose.yaml

@@ -0,0 +1,12 @@
+services:
+  serve:
+    image: honkit/honkit:latest
+    command: npm run start
+    ports:
+      - "4040:4040"
+      # livereload port. Can't be changed (https://github.com/GitbookIO/plugin-livereload/pull/1)
+      - "35729:35729"
+    volumes:
+      - .:/app
+    working_dir: /app
+    platform: linux/amd64

package.json

@@ -4,6 +4,8 @@
   "description": "",
   "main": "index.js",
   "scripts": {
+    "start": "honkit serve --port 4040",
+    "build": "honkit build",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [],