From 5ba571297696da5c9f0ec76555d51187b79af4b3 Mon Sep 17 00:00:00 2001 From: Simon Zambrovski Date: Fri, 31 May 2024 15:07:14 +0200 Subject: [PATCH 1/2] setup docs, fix #61 --- .github/dependabot.yml | 6 ++ .github/workflows/development.yml | 2 +- .github/workflows/docs.yml | 62 +++++++++++++ .github/workflows/master.yml | 2 +- docs/CNAME | 1 + docs/assets/css/extra.css | 64 +++++++++++++ docs/developer-guide/contribution.md | 25 +++++ docs/developer-guide/project-setup.md | 126 ++++++++++++++++++++++++++ docs/getting-started/index.md | 4 + docs/index.md | 16 ++++ docs/reference-guide/index.md | 6 ++ docs/requirements.txt | 5 + mkdocs.yml | 95 +++++++++++++++++++ 13 files changed, 412 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/CNAME create mode 100644 docs/assets/css/extra.css create mode 100644 docs/developer-guide/contribution.md create mode 100644 docs/developer-guide/project-setup.md create mode 100644 docs/getting-started/index.md create mode 100644 docs/index.md create mode 100644 docs/reference-guide/index.md create mode 100644 docs/requirements.txt create mode 100644 mkdocs.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 4f8dcdd6..86606383 100644 --- a/.github/dependabot.yml +++ b/.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" diff --git a/.github/workflows/development.yml b/.github/workflows/development.yml index 6bd5024e..51b624b2 100644 --- a/.github/workflows/development.yml +++ b/.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 }} diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..80849e99 --- /dev/null +++ b/.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 diff --git a/.github/workflows/master.yml b/.github/workflows/master.yml index d1f9956d..3059bb80 100644 --- a/.github/workflows/master.yml +++ b/.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 diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 00000000..64640d65 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +www.holunda.io diff --git a/docs/assets/css/extra.css b/docs/assets/css/extra.css new file mode 100644 index 00000000..c17e53ec --- /dev/null +++ b/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); +} diff --git a/docs/developer-guide/contribution.md b/docs/developer-guide/contribution.md new file mode 100644 index 00000000..bd4ceb16 --- /dev/null +++ b/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 diff --git a/docs/developer-guide/project-setup.md b/docs/developer-guide/project-setup.md new file mode 100644 index 00000000..38593279 --- /dev/null +++ b/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/` 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 +true +``` + +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="" +export GPG_PASSPHRASE="" +./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. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md new file mode 100644 index 00000000..78303ad0 --- /dev/null +++ b/docs/getting-started/index.md @@ -0,0 +1,4 @@ +--- +title: Getting started +--- + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..54285218 --- /dev/null +++ b/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) diff --git a/docs/reference-guide/index.md b/docs/reference-guide/index.md new file mode 100644 index 00000000..17cd07ad --- /dev/null +++ b/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 ... + diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..b17c2366 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +mkdocs +mkdocs-git-committers-plugin +mkdocs-material +mike +mkdocs-git-revision-date-localized-plugin diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..c74712fd --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,95 @@ +# ############################### +# Main config file for MkDocs. +# ############################### +# +# To run: +# mkdocs serve +# More help: https://www.holunda.io/camunda-bpm-taskpool/developer-guide/project-setup.html#build-documentation +# ############################### + +site_name: Avro Kotlin +site_url: https://avro-kotlin.toolisticon.io/ +site_author: Holisticon Crafters +site_description: >- + Avro Kotlin provides utilities to improve working experience with Apache Avro and Kotlin. + +copyright: Copyright © 2024, Holisticon AG + +use_directory_urls: false + +# Repository +repo_name: toolisticon/avro-kotlin +repo_url: https://github.com/toolisticon/avro-kotlin/ +edit_uri: edit/develop/docs/ + +markdown_extensions: + - attr_list + - toc: + permalink: "#" + - pymdownx.highlight + - pymdownx.superfences + - pymdownx.details + - admonition + + +theme: + name: material + features: + - navigation.instant # When instant loading is enabled, clicks on all internal links will be intercepted and dispatched via XHR without fully reloading the page + - navigation.tabs # add top level nav items into a horizoneal menu + - navigation.tabs.sticky # make horizontal menu sticky (insider feature) + - navigation.sections + - navigation.top # add "navigate to top" page icon on bottom left + - toc.integrate # integrate site TOC into the menu on the left + logo: assets/img/logo.svg + icon: + repo: fontawesome/brands/github + font: + text: Roboto + code: Roboto Mono + palette: + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/weather-sunny + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/weather-night + name: Switch to dark mode + +extra_css: [ assets/css/extra.css ] + +extra: + social: + - icon: fontawesome/brands/twitter + name: Holisticon on Twitter + link: https://twitter.com/holisticon + - icon: fontawesome/brands/medium + name: Holisticon Crafters on Medium + link: https://medium.com/holisticon-consultants/tagged/mpb + version: + provider: mike + +plugins: + - search + - mike: + # these fields are all optional; the defaults are as below... + version_selector: true # set to false, in order to leave out the version selector + css_dir: css # the directory to put the version selector's CSS + javascript_dir: js # the directory to put the version selector's JS + canonical_version: null # the version for ; `null` + # uses the version specified via `mike deploy` + - git-revision-date-localized: + type: date + fallback_to_build_date: true + +nav: + - Home: index.md + - Getting Started: getting-started/index.md + - Reference: + - Reference Overview: reference-guide/index.md + - Developers: + - Contribution: developer-guide/contribution.md + - Project Setup: developer-guide/project-setup.md From 97d31bed7f452182bf01a239a2abf0abb3d43cc3 Mon Sep 17 00:00:00 2001 From: Simon Zambrovski Date: Fri, 31 May 2024 15:09:03 +0200 Subject: [PATCH 2/2] adding assets --- docs/assets/img/logo.svg | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 docs/assets/img/logo.svg diff --git a/docs/assets/img/logo.svg b/docs/assets/img/logo.svg new file mode 100644 index 00000000..0386c41f --- /dev/null +++ b/docs/assets/img/logo.svg @@ -0,0 +1,11 @@ + + + + + +