Add linting to the CI

This commit lints all the file with the vmdfmt tool. It also adds this tool to the CI in a workflow that checks that the book builds and that the files are well formatted. Signed-off-by: Hugues de Valon <[email protected]>
parallaxsecond · Feb 11, 2020 · ec21c51 · ec21c51
1 parent e743c10
commit ec21c51
Show file tree

Hide file tree

Showing 39 changed files with 1,823 additions and 1,348 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,23 +1,29 @@
-name: Build Github mdBook
+name: Continuous Integration
 
-on:
-  push:
-    branches:
-    - master
+on: [push, pull_request]
 
 jobs:
-  deploy:
-    runs-on: ubuntu-18.04
+  build:
+    name: Build
+    runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v1
     - name: Install mdbook
       run: cargo install mdbook
     - name: Build book
       run: mdbook build
 
-    - name: Deploy to GitHub Pages
-      uses: peaceiris/actions-gh-pages@v2
-      env:
-        ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
-        PUBLISH_BRANCH: gh-pages
-        PUBLISH_DIR: ./book
+  format:
+    name: Check formatting
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: Create a Go workspace and install vmdfmt
+      run: |
+          mkdir /tmp/go
+          export GOPATH=/tmp/go
+          go get github.com/bobertlo/vmd/cmd/vmdfmt
+    - name: Check formatting
+      run: |
+          export PATH="/tmp/go/bin:$PATH"
+          ./ci/check_format.sh
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -0,0 +1,23 @@
+name: Deploy
+
+on:
+  push:
+    branches:
+    - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-18.04
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install mdbook
+      run: cargo install mdbook
+    - name: Build book
+      run: mdbook build
+
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v2
+      env:
+        ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+        PUBLISH_BRANCH: gh-pages
+        PUBLISH_DIR: ./book
diff --git a/README.md b/README.md
@@ -14,11 +14,13 @@
   -- See the License for the specific language governing permissions and
   -- limitations under the License.
 --->
+# The Parsec Book 📖
 
-![Parsec](parsec.png)
-# Parsec documentation
+![](https://github.com/parallaxsecond/parsec-book/workflows/Continuous%20Integration/badge.svg)
+![](https://github.com/parallaxsecond/parsec-book/workflows/Deploy/badge.svg)
 
-Official technical documentation, user and developer guides of the Parsec project.
+Official Parsec documentation source. User, Client and Service developer guides
+of the Parsec project.
 
 ## Using
 
@@ -33,6 +35,14 @@ $ cargo install mdbook
 $ mdbook serve
 ```
 
+This book uses the [Versioned Markdown](https://github.com/bobertlo/vmd) format which allows
+us to use the `vmdfmt` formatting tool. The lines should be wrapped after 100 characters.
+If you have the `vmdfmt` command available on the command-line,
+```bash
+$ ./ci/check_format.sh
+```
+will check if your files are formatted correctly.
+
 ## Contributing
 
 Please check the [**Contributing**](CONTRIBUTING.md) to know more about the contribution process.

diff --git a/book.toml b/book.toml
@@ -1,5 +1,5 @@
 [book]
-title = "Parsec Documentation"
+title = "The Parsec Book"
 authors = ["Adam Parco <[email protected]>",
            "Sabree Blackmon <[email protected]>",
            "Hugues de Valon <[email protected]>",

diff --git a/ci/check_format.sh b/ci/check_format.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+# ------------------------------------------------------------------------------
+# Copyright (c) 2020, Arm Limited, All Rights Reserved
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#          http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ------------------------------------------------------------------------------
+
+set -euf -o pipefail
+
+# Check the git diff between the vmdfmt-formatted file and the actual file to
+# make sure they match.
+
+OUT_DIR="/tmp/parsec-book-ci"
+mkdir -p $OUT_DIR
+
+MARKDOWN_FILES=`find src -name "*.md"`
+for f in $MARKDOWN_FILES
+do
+	echo "Checking file \"$f\""
+	vmdfmt -cols 100 $f > $OUT_DIR/$(basename $f)
+	git diff --exit-code $f $OUT_DIR/$(basename $f)
+done
+
+rm -rf $OUT_DIR
diff --git a/parsec.png b/parsec.png
diff --git a/src/README.md b/src/README.md
@@ -1,38 +1,24 @@
-<!--
-  -- Copyright (c) 2019, Arm Limited, All Rights Reserved
-  -- SPDX-License-Identifier: Apache-2.0
-  --
-  -- Licensed under the Apache License, Version 2.0 (the "License"); you may
-  -- not use this file except in compliance with the License.
-  -- You may obtain a copy of the License at
-  --
-  -- http://www.apache.org/licenses/LICENSE-2.0
-  --
-  -- Unless required by applicable law or agreed to in writing, software
-  -- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-  -- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-  -- See the License for the specific language governing permissions and
-  -- limitations under the License.
---->
-
 # Parsec
 
-**Parsec** is the **P**latform **A**bst**R**action for **SEC**urity,
-a new open-source initiative to provide a common API to secure services in a platform-agnostic way.
+**Parsec** is the **P**latform **A**bst**R**action for **SEC**urity, a new open-source initiative to
+provide a common API to secure services in a platform-agnostic way.
 
 Find here all the technical documentation of Parsec, alongside user and developer guides.
 
 # Disclaimer
 
 Parsec is a new open source project and is under development. This code repository is being made
-available so that the developer community can learn and give feedback about the new interfaces and the concepts of platform-agnostic security.
-The implementation that is provided is suitable for exploratory testing and experimentation only.
-This test implementation does not offer any tangible security benefits and therefore is not
-suitable for use in production. Documentation pages may be incomplete and are subject to change
-without notice. Interfaces may change in such a way as to break compatibility with client code.
-Contributions from the developer community are welcome. Please refer to the contribution guidelines.
+available so that the developer community can learn and give feedback about the new interfaces and
+the concepts of platform-agnostic security. The implementation that is provided is suitable for
+exploratory testing and experimentation only. This test implementation does not offer any tangible
+security benefits and therefore is not suitable for use in production. Documentation pages may be
+incomplete and are subject to change without notice. Interfaces may change in such a way as to break
+compatibility with client code. Contributions from the developer community are welcome. Please refer
+to the contribution guidelines.
 
 # License
 
-Parsec and all the repositories under the `parallaxsecond` organization are provided under Apache-2.0.
-Contributions to this project are accepted under the same license.
+Parsec and all the repositories under the `parallaxsecond` organization are provided under
+Apache-2.0. Contributions to this project are accepted under the same license.
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -1,51 +1,36 @@
-<!--
-  -- Copyright (c) 2019, Arm Limited, All Rights Reserved
-  -- SPDX-License-Identifier: Apache-2.0
-  --
-  -- Licensed under the Apache License, Version 2.0 (the "License"); you may
-  -- not use this file except in compliance with the License.
-  -- You may obtain a copy of the License at
-  --
-  -- http://www.apache.org/licenses/LICENSE-2.0
-  --
-  -- Unless required by applicable law or agreed to in writing, software
-  -- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-  -- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-  -- See the License for the specific language governing permissions and
-  -- limitations under the License.
---->
-
 # Summary
 
 - [Introduction](README.md)
 - [Overview](overview.md)
 - [Parsec for users](parsec_users.md)
 - [Parsec for client developers](parsec_client/README.md)
-    - [Operations](parsec_client/operations/README.md)
-        - [AddClient](parsec_client/operations/add_client.md)
-        - [ListOpcodes](parsec_client/operations/list_opcodes.md)
-        - [ListProviders](parsec_client/operations/list_providers.md)
-        - [Ping](parsec_client/operations/ping.md)
-        - [ProveClient](parsec_client/operations/prove_client.md)
-        - [PsaAsymmetricSign](parsec_client/operations/psa_asymmetric_sign.md)
-        - [PsaAsymmetricVerify](parsec_client/operations/psa_asymmetric_verify.md)
-        - [PsaCreateKey](parsec_client/operations/psa_create_key.md)
-        - [PsaDestroyKey](parsec_client/operations/psa_destroy_key.md)
-        - [PsaExportPublicKey](parsec_client/operations/psa_export_public_key.md)
-        - [PsaImportKey](parsec_client/operations/psa_import_key.md)
-        - [ShareTrustBundle](parsec_client/operations/share_trust_bundle.md)
-        - [Key Attributes](parsec_client/operations/key_attributes.md)
-    - [API Overview](parsec_client/api_overview.md)
-    - [Status Codes](parsec_client/status_codes.md)
-    - [Wire Protocol](parsec_client/wire_protocol.md)
-    - [Writing a new Parsec Client Library](parsec_client/writing_library.md)
+   - [Operations](parsec_client/operations/README.md)
+      - [AddClient](parsec_client/operations/add_client.md)
+      - [ListOpcodes](parsec_client/operations/list_opcodes.md)
+      - [ListProviders](parsec_client/operations/list_providers.md)
+      - [Ping](parsec_client/operations/ping.md)
+      - [ProveClient](parsec_client/operations/prove_client.md)
+      - [PsaAsymmetricSign](parsec_client/operations/psa_asymmetric_sign.md)
+      - [PsaAsymmetricVerify](parsec_client/operations/psa_asymmetric_verify.md)
+      - [PsaCreateKey](parsec_client/operations/psa_create_key.md)
+      - [PsaDestroyKey](parsec_client/operations/psa_destroy_key.md)
+      - [PsaExportPublicKey](parsec_client/operations/psa_export_public_key.md)
+      - [PsaImportKey](parsec_client/operations/psa_import_key.md)
+      - [ShareTrustBundle](parsec_client/operations/share_trust_bundle.md)
+      - [Key Attributes](parsec_client/operations/key_attributes.md)
+   - [API Overview](parsec_client/api_overview.md)
+   - [Status Codes](parsec_client/status_codes.md)
+   - [Wire Protocol](parsec_client/wire_protocol.md)
+   - [Writing a new Parsec Client Library](parsec_client/writing_library.md)
 - [Parsec for service developers](parsec_service/README.md)
-    - [System Architecture](parsec_service/system_architecture.md)
-    - [Interfaces and Dataflow](parsec_service/interfaces_and_dataflow.md)
-    - [Source Code Structure](parsec_service/source_code_structure.md)
-    - [Providers](parsec_service/providers.md)
-    - [Adding a new Parsec Provider](parsec_service/adding_provider.md)
-    - [How to build and run Parsec](parsec_service/build_run.md)
-    - [How to install Parsec on Linux](parsec_service/install_parsec_linux.md)
-    - [Parsec Configuration](parsec_service/configuration.md)
-    - [How to test Parsec](parsec_service/test.md)
+   - [System Architecture](parsec_service/system_architecture.md)
+   - [Interfaces and Dataflow](parsec_service/interfaces_and_dataflow.md)
+   - [Source Code Structure](parsec_service/source_code_structure.md)
+   - [Providers](parsec_service/providers.md)
+   - [Adding a new Parsec Provider](parsec_service/adding_provider.md)
+   - [How to build and run Parsec](parsec_service/build_run.md)
+   - [How to install Parsec on Linux](parsec_service/install_parsec_linux.md)
+   - [Parsec Configuration](parsec_service/configuration.md)
+   - [How to test Parsec](parsec_service/test.md)
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*