Migrate to mkdocs (#94)

* update * update * update * update * update * update * update * update * update * update * update * update
stakater · May 27, 2024 · 9bd293e · 9bd293e
1 parent 4542f4a
commit 9bd293e
Show file tree

Hide file tree

Showing 52 changed files with 1,147 additions and 10,990 deletions.
diff --git a/.github/md_config.json b/.github/md_config.json
@@ -0,0 +1,17 @@
+{
+  "aliveStatusCodes": [429, 200, 520], 
+  "ignorePatterns": [
+    {
+      "pattern": "^(https://stakater).+"
+    },
+    {
+      "pattern": "^(http://nexus).+"
+    },
+    {
+      "pattern": "^(https://nexus).+"
+    },
+    {
+      "pattern": "^(https://docs.github.com).+"
+    }
+  ]
+}
diff --git a/.github/workflows/pull_request.yaml b/.github/workflows/pull_request.yaml
@@ -6,6 +6,12 @@ on:
       - 'master'
 
 jobs:
+  qa:
+    uses: stakater/.github/.github/workflows/pull_request_doc_qa.yaml@v0.0.75
+    with:
+      MD_CONFIG: .github/md_config.json
+      DOC_SRC: content
+      MD_LINT_CONFIG: .markdownlint.yaml
   build:
     uses: stakater/.github/.github/workflows/pull_request_container_build.yaml@v0.0.75
     with:

diff --git a/.gitignore b/.gitignore
@@ -2,4 +2,9 @@ node_modules/
 .vuepress/dist/
 .DS_Store
 .vscode
-.idea
+.idea
+
+dist/
+site/
+styles/
+/mkdocs.yml
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "theme_common"]
+	path = theme_common
+	url = git@github.com:stakater/stakater-docs-mkdocs-theme.git
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
@@ -0,0 +1,8 @@
+{
+  "MD007": { "indent": 4 },
+  "MD013": false,
+  "MD024": false,
+  "MD029": { "style": one },
+  "MD033": false,
+  "MD046": false,
+}
diff --git a/.vale.ini b/.vale.ini
@@ -0,0 +1,10 @@
+StylesPath = styles
+MinAlertLevel = warning
+
+Packages = https://github.com/stakater/vale-package/releases/download/v0.0.21/Stakater.zip
+Vocab = Stakater
+
+# Only check MarkDown files
+[*.md]
+
+BasedOnStyles = Vale
diff --git a/.vuepress/config.js b/.vuepress/config.js
diff --git a/Dockerfile b/Dockerfile
@@ -1,10 +1,6 @@
-FROM registry.access.redhat.com/ubi8/nodejs-12
+FROM python:3.12 as builder
 
-LABEL name="Stakater Developer Handbook" \    
-      maintainer="Stakater <hello@stakater.com>" \
-      vendor="Stakater" \
-      release="1" \
-      summary="Developer Handbook" 
+RUN pip3 install mkdocs-mermaid2-plugin mkdocs-table-reader-plugin mkdocs-include-markdown-plugin
 
 # set workdir
 RUN mkdir -p $HOME/application
@@ -13,22 +9,22 @@ WORKDIR $HOME/application
 # copy the entire application
 COPY --chown=1001:root . .
 
-# install yarn globaly
-RUN npm install -g yarn
-
-# download the application dependencies
-RUN yarn install
-
-# build the application
-RUN yarn run build
-
-# Change ownership of cache to make it writable
-RUN chown -R 1001 ~/.cache
-
-# Change permissions to fix EACCESS permission error
-RUN chmod -R 755 $HOME
+# build the docs
+RUN chmod +x prepare_theme.sh && ./prepare_theme.sh
+RUN mkdocs build
+FROM nginxinc/nginx-unprivileged:1.26-alpine as deploy
+COPY --from=builder $HOME/application/site/ /usr/share/nginx/html/
+COPY default.conf /etc/nginx/conf.d/
 
 # set non-root user
 USER 1001
 
-ENTRYPOINT ["yarn", "run", "serve"]
+LABEL name="Stakater Developer Handbook" \
+      maintainer="Stakater <hello@stakater.com>" \
+      vendor="Stakater" \
+      release="1" \
+      summary="Developer Handbook"
+
+EXPOSE 8080:8080/tcp
+
+CMD ["nginx", "-g", "daemon off;"]
diff --git a/README.md b/README.md
@@ -1,21 +1 @@
-# developer-handbook
-
-Local development
-
-## MacOS
-
-All dependencies for the developer handbook is handled with yarn.
-
-```bash
-# install nodejs with brew
-brew install node
-
-# install yarn with npm
-npm install -g yarn
-
-# install dependencies with yarn
-yarn
-
-# start local development server
-yarn run dev
-```
+# Developer Handbook
diff --git a/content/api/foundations.md b/content/api/foundations.md
@@ -4,7 +4,7 @@ The Foundations section outlines the design principles upon which the rest of th
 
 ## Provide Request-Ids for Introspection
 
-Include a `Request-Id` header in each API response, populated with a UUID value. By logging these values on the client, server and any backing services, it provides a mechanism to trace, diagnose and debug requests.
+Include a `Request-Id` header in each API response, populated with a uuid value. By logging these values on the client, server and any backing services, it provides a mechanism to trace, diagnose and debug requests.
 
 ## Divide Large Responses Across Requests with Ranges
 
@@ -14,7 +14,7 @@ to specify when more data is available and how to retrieve it. See the
 for the details of request and response headers, status codes, limits,
 ordering, and iteration.
 
-# Require Secure Connections
+## Require Secure Connections
 
 Require secure connections with TLS to access the API, without exception.
 It’s not worth trying to figure out or explain when it is OK to use TLS
@@ -25,10 +25,10 @@ http or port 80 to avoid any insecure data exchange. In environments where this
 is not possible, respond with `403 Forbidden`.
 
 Redirects are discouraged since they allow sloppy/bad client behaviour without
-providing any clear gain.  Clients that rely on redirects double up on
+providing any clear gain. Clients that rely on redirects double up on
 server traffic and render TLS useless since sensitive data will already
  have been exposed during the first call.
- 
+
 ## Separate Concerns
 
 Keep things simple while designing by separating the concerns between the
@@ -37,14 +37,13 @@ allows for greater focus on larger and harder problems.
 
 Requests and responses will be made to address a particular resource or
 collection. Use the path to indicate identity, the body to transfer the
-contents and headers to communicate metadata. Query params may be used as a
+contents and headers to communicate metadata. Query parameters may be used as a
 means to pass header information also in edge cases, but headers are preferred
 as they are more flexible and can convey more diverse information.
 
-## Support ETags for Caching
+## Support `ETags` for Caching
 
 Include an `ETag` header in all responses, identifying the specific
 version of the returned resource. This allows users to cache resources
 and use requests with this value in the `If-None-Match` header to determine
 if the cache should be updated.
-
diff --git a/content/api/general-guidelines.md b/content/api/general-guidelines.md
@@ -20,7 +20,7 @@ By defining APIs outside the code, we want to facilitate early review feedback a
 Moreover, API definitions with standardized specification format also facilitate...
 
 - single source of truth for the API specification; it is a crucial part of a contract between service provider and client users
-- infrastructure tooling for API discovery, API GUIs, API documents, automated quality checks
+- infrastructure tooling for API discovery, API GUI, API documents, automated quality checks
 
 It is important to learn, that API First is not in conflict with the agile development principles that we love. Service applications should evolve incrementally — and so its APIs. Of course, API specification will and should evolve iteratively in different cycles, each starting with draft status and early team and peer review feedback.
 
@@ -32,4 +32,4 @@ We use the OpenAPI specification (aka Swagger spec) as standard for REST API def
 
 We also call the OpenAPI API definition the "API Reference definition" (or "API definition"); it provides all information needed by an experienced API client developer to use this API.
 
-The OpenAPI API specification file should be subject of version control together with source code management. Services also have to support an endpoint to access the API Reference definition for their external API(s).
+The OpenAPI API specification file should be subject of version control together with source code management. Services also have to support an endpoint to access the API Reference definition for their external API(s).
diff --git a/content/api/how-to-model-workflows-in-rest-apis.md b/content/api/how-to-model-workflows-in-rest-apis.md
@@ -5,8 +5,8 @@ RESTful Web Services are awesome for performing basic CRUD operations on databas
 There are three options:
 
 1. Use an Attribute for the Workflow’s State
-2. Use Hyperlinks for Workflow Transitions
-3. Use a Subresource for Workflow Transitions
+1. Use Hyperlinks for Workflow Transitions
+1. Use a `Subresource` for Workflow Transitions
 
 ## So which one should I pick?
 
@@ -18,11 +18,10 @@ As always, it depends on the context, but here are some quick guidelines:
 | --- | --- |
 | State Attribute | When there are no restrictions on the transitions. You can go from any state to any state at any time. The states are basically nothing more than a list of values. |
 | Transition Links | There are limits to which states you can go to depending on the current state. |
-| Transition Subresource | The workflow is configurable by users, so states and transitions among them are not fixed, but can be changed at runtime. |
-
+| Transition `Subresource` | The workflow is configurable by users, so states and transitions among them are not fixed, but can be changed at runtime. |
 
 ## Reference
 
 Read following for more details:
 
-- https://www.kennethlange.com/how-to-model-workflows-in-rest-apis/
+- [How to Model Workflows in REST APIs](https://www.kennethlange.com/how-to-model-workflows-in-rest-apis/)