Merge pull request #68 from toolisticon/feature/docs

Create documentation site

.github/dependabot.yml

@@ -7,3 +7,9 @@ updates:
     open-pull-requests-limit: 19
     labels:
       - "Type: dependencies"
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: daily
+    labels:
+      - "Type: dependencies"

.github/workflows/development.yml

@@ -14,7 +14,7 @@ jobs:
     steps:
       # Checkout the code
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Expose branch name
         run: echo ${{ github.ref }}

.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+name: Build the docs
+
+on:
+  push:
+    branches:
+      - develop
+    tags:
+      - '*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+          cache: pip
+
+      - name: Upgrade pip
+        run: |
+          # install pip=>20.1 to use "pip cache dir"
+          python3 -m pip install --upgrade pip
+
+      - name: Install dependencies
+        run: python3 -m pip install -r ./docs/requirements.txt
+
+      - name: Set git username and email
+        run: |
+          #
+          git config --global user.email "${GH_USERNAME}@users.noreply.github.com"
+          git config --global user.name "${GH_USERNAME}"
+        env:
+          GH_USERNAME: ${{ github.actor }}
+
+      - name: Pre-fetch the gh-pages branch
+        run: git fetch --depth=1
+
+      - name: Build docs with MkDocs
+        run: mkdocs build
+
+      - name: Read the tag name
+        id: get_tag_name
+        if: startsWith(github.ref, 'refs/tags/')
+        run: echo ::set-output name=TAG_NAME::${GITHUB_REF/refs\/tags\//}
+
+      # This is for a tagged version
+      - name: Create a new version of documentation and push to GH pages.
+        if: startsWith(github.ref, 'refs/tags/')
+        run: mike deploy ${{ steps.get_tag_name.outputs.TAG_NAME }} stable --push --update-aliases
+
+      - name: Make stable to default.
+        if: startsWith(github.ref, 'refs/tags/')
+        run: mike set-default stable --push
+
+      # This is for develop
+      - name: Deploy latest develop snapshot docs to GH pages.
+        if: github.ref == 'refs/heads/develop'
+        run: mike deploy snapshot --push --update-aliases

.github/workflows/master.yml

@@ -11,7 +11,7 @@ jobs:
     name: Build and run tests
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       # Setup JDK and .m2/settings.xml
       - name: Set up JDK 17

docs/CNAME

@@ -0,0 +1 @@
+www.holunda.io

docs/assets/css/extra.css

@@ -0,0 +1,64 @@
+/*
+ * General customizations
+ */
+/* Customize logo size */
+.md-header__button.md-logo img, .md-header__button.md-logo {
+  height: 15%;
+  width: 15%;
+}
+
+
+
+[data-md-color-scheme="default"] {
+
+  /*
+ Holisticon colors
+ */
+  --bright-green: #C8FFA5;
+  --black-green: #102924;
+  --forest-green: #1E4132;
+  --blue-gray: #C7CFEB;
+  --blue-gray-d2: #9CA4B8;
+  --black: #141419;
+  --forest-green-b2: #396D55;
+  --forest-green-b3: #478467;
+
+  --red: #ff0000;
+
+
+  /*
+   Default colors adjustments
+   */
+  --md-primary-fg-color: var(--forest-green);
+  --md-accent-fg-color: var(--blue-gray-d2);
+  --md-footer-bg-color: var(--forest-green);
+  --md-typeset-a-color: var(--forest-green-b2);
+}
+
+[data-md-color-scheme="slate"] {
+
+  --bright-green: #C8FFA5;
+  --black-green: #102924;
+  --forest-green: #1E4132;
+  --blue-gray: #C7CFEB;
+  --black: #141419;
+
+  --forest-green-b2: #396D55;
+  --forest-green-b3: #478467;
+
+
+  --red: #ff0000;
+  /*
+   Default colors adjustments
+   */
+  --md-default-bg-color: var(--black-green);
+  --md-primary-fg-color: var(--black-green);
+  --md-default-fg-color--light: var(--bright-green);
+  --md-default-fg-color--dark: var(--bright-green);
+
+  --md-typeset-color: var(--bright-green);
+  --md-typeset-a-color: var(--blue-gray);
+
+  --md-accent-fg-color: var(--forest-green-b3);
+  --md-footer-bg-color: var(--black);
+}

docs/developer-guide/contribution.md

@@ -0,0 +1,25 @@
+---
+title: Contribution
+---
+
+There are several ways in which you may contribute to this project.
+
+* [File issues](https://github.com/toolisticon/avro-kotlin/issues)
+* Submit a pull requests
+
+## Found a bug or missing feature?
+
+Please [file an issue](https://github.com/toolisticon/avro-kotlin/issues) in our
+issue tracking system.
+
+## Submit a Pull Request
+
+If you found a solution to an [open issue](https://github.com/toolisticon/avro-kotlin/issues)
+and implemented it, we would be happy to add your contribution in the code base. For doing so,
+please create a pull request. Prior to that, please make sure you:
+
+- rebase against the `develop` branch
+- stick to project coding conventions
+- added test cases for the problem you are solving
+- added docs, describing the change
+- generally comply with codacy report

docs/developer-guide/project-setup.md

@@ -0,0 +1,126 @@
+---
+title: Project Setup
+pageId: 'project-setup'
+---
+
+If you are interested in developing and building the project please follow the following instruction.
+
+## Version control
+
+To get sources of the project, please execute:
+
+```bash
+git clone https://github.com/toolisticon/avro-kotlin.git
+cd camunda-bpm-taskpool
+```
+
+We are using gitflow in our git SCM. That means that you should start from `develop` branch,
+create a `feature/<name>` out of it and once it is completed create a pull request containing
+it. Please squash your commits before submitting and use semantic commit messages, if possible.
+
+## Project Build
+
+Perform the following steps to get a development setup up and running.
+
+```bash
+./mvnw clean install
+```
+
+## Integration Tests
+
+By default, the build command will ignore the run of `failsafe` Maven plugin executing the integration tests
+(usual JUnit tests with class names ending with ITest). In order to run integration tests, please
+call from your command line:
+
+```bash
+./mvnw integration-test failsafe:verify -Pitest
+```
+
+### Build Documentation
+
+We are using MkDocs for generation of a static site documentation and rely on Markdown as much as possible.
+MkDocs is written in Python 3 and needs to be installed on your machine. For the installation please run the following
+command from your command line:
+
+```bash
+python3 -m pip install --upgrade pip
+python3 -m pip install -r ./docs/requirements.txt
+```
+
+For creation of documentation, please run:
+
+```bash
+mkdocs build
+```
+
+The docs are generated into `site` directory.
+
+!!! note
+    If you want to develop your docs in 'live' mode, run `mkdocs serve` and access the [http://localhost:8000/](http://localhost:8000/) from your browser.
+
+## Continuous Integration
+
+Travis CI is building all branches on commit hook. In addition, a private-hosted Jenkins CI
+is used to build the releases.
+
+## Release Management
+
+Release management has been set up for use of Sonatype Nexus (= Maven Central)
+
+### What modules get deployed to repository
+
+Every module is enabled by default. If you want to change this, please provide the property
+
+```xml
+<maven.deploy.skip>true</maven.deploy.skip>
+```
+
+inside the corresponding `pom.xml`. Currently, all examples are _EXCLUDED_ from publication into Maven Central.
+
+### Trigger new release
+
+!!! warning
+    This operation requires special permissions.
+
+We use gitflow for development (see [A successful git branching model](http://nvie.com/posts/a-successful-git-branching-model/) for more details). You could use gitflow with native git commands, but then you would have to change the versions in the poms manually. Therefore, we use the [mvn gitflow plugin](https://github.com/aleksandr-m/gitflow-maven-plugin/), which handles this and other things nicely.
+
+You can build a release with:
+
+```bash
+./mvnw gitflow:release-start
+./mvnw gitflow:release-finish
+```
+
+This will update the versions in the `pom.xml` s accordingly and push the release tag to the `master` branch
+and update the `develop` branch for the new development version.
+
+### Trigger a deploy
+
+!!! warning
+    This operation requires special permissions.
+
+Currently, CI allows for deployment of artifacts to Maven Central and is executed using github actions.
+This means, that a push to `master` branch will start the corresponding build job, and if successful the
+artifacts will get into `Staging Repositories` of OSS Sonatype without manual intervention.
+
+### Run deploy from local machine
+
+!!! warning
+    This operation requires special permissions.
+
+If you still want to execute the deployment from your local machine, you need to have GPG keys at place and
+to execute the following command on the `master` branch:
+
+```bash
+export GPG_KEYNAME="<keyname>"
+export GPG_PASSPHRASE="<secret>"
+./mvnw clean deploy -B -DskipTests -DskipExamples -Prelease -Dgpg.keyname=$GPG_KEYNAME -Dgpg.passphrase=$GPG_PASSPHRASE
+```
+
+### Release to public repositories
+
+!!! warning
+     This operation requires special permissions.
+
+The deployment job will publish the artifacts to Nexus OSS staging repositories. Currently, all snapshots get into OSS Sonatype Snapshot
+repository and all releases to Maven Central automatically.

docs/getting-started/index.md

@@ -0,0 +1,4 @@
+---
+title: Getting started
+---
+

docs/index.md

@@ -0,0 +1,16 @@
+## Why should I use this?
+
+* 
+
+
+## How to start?
+
+We provide documentation for different people and different tasks. A good starting point is the
+[Getting Started](./getting-started/). You might want to look at [Reference Guide](./reference-guide/).
+
+## Get in touch
+
+If you are missing a feature, have a question regarding usage or deployment, you should definitely get in touch
+with us. There are various ways to do so:
+
+[![Github Issues](https://img.shields.io/github/issues/toolisticon/avro-kotlin)](https://github.com/holunda-io/camunda-bpm-taskpool/issues)

docs/reference-guide/index.md

@@ -0,0 +1,6 @@
+---
+title: Reference Guide
+---
+
+This reference guide is a primary source of information in order to understand how ...
+

docs/requirements.txt

@@ -0,0 +1,5 @@
+mkdocs
+mkdocs-git-committers-plugin
+mkdocs-material
+mike
+mkdocs-git-revision-date-localized-plugin