Feature/deploy

.github/workflows/build-pipeline.yaml

@@ -0,0 +1,143 @@
+# This Github Action will:
+#     jobs:
+#        build:                  install Python dependencies
+#                                run tests and lint with a single version of Python
+#        pypi-publish:           build and publish to PyPi (main branch only) - if build job passes
+#        documentation-publish:  build the sphinx-based documentation (release branch only) - if build job passes
+
+name: Build Pipeline
+
+on:
+  push:
+    branches:
+      # Push events to main branch
+      - main
+      # Push events to develop branch
+      - develop
+      # Push events to a release branch
+      - release/*
+      # Push events to a feature branch
+      - feature/*
+  pull_request:
+    branches:
+      # PR events to main branch
+      - main
+      # PR events to develop branch
+      - develop
+      # PR events to a release branch
+      - release/*
+
+jobs:
+  sonarcloud:
+    name: SonarCloud
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
+      - name: SonarCloud Scan
+        uses: SonarSource/sonarcloud-github-action@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Needed to get PR information, if any
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+  build:
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.7", "3.8", "3.9", "3.10", pypy-3.8]
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Get the current branch name
+      shell: bash
+      run: echo "::set-output name=branch::${GITHUB_REF#refs/heads/}"; echo "Branch Name = ${GITHUB_REF#refs/heads/}"
+      id: branch_name
+    - name: Printing Github Context
+      env:
+        GITHUB_CONTEXT: ${{ toJSON(github) }}
+      run: echo "$GITHUB_CONTEXT"
+    - name: Install dependencies
+      run: |
+        # Update pip and install flake8, pytest and coverage
+        python -m pip install --upgrade pip
+        pip install flake8 pytest coverage
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi  
+    - name: Lint with flake8
+      run: |
+        # Stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      working-directory: ./test
+      run: |
+        # Run all tests
+        pytest test_adr_viewer.py
+    - name: Test accessibility
+      working-directory: .
+      run: |
+        # Install accessibility suite
+        npm install -g pa11y
+        python setup.py install
+        adr-viewer --template-dir adr_viewer/templates
+        pa11y ./index.html --config pa11y.json
+  pypi-publish:
+    needs: [build, sonarcloud]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+    - name: Get the current branch name
+      shell: bash
+      run: echo "::set-output name=branch::${GITHUB_REF#refs/heads/}"; echo "Branch Name = ${GITHUB_REF#refs/heads/}"
+      id: branch_name
+    - name: Build and publish to pypi if on a release branch
+      working-directory: .
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_DEPLOY }}
+      run: |
+        BRANCH_NAME="${{ steps.branch_name.outputs.branch }}"
+        if [[ "${BRANCH_NAME:0:8}" = "release/" ]]; then
+        RELEASE_NAME="${BRANCH_NAME:8}"
+        echo "Release Name: ${RELEASE_NAME}" ;
+        echo "Publishing Release ${RELEASE_NAME} to PyPi"
+        python -m pip install build ;
+        python -m pip install twine ;
+        python -m build ;
+        python -m twine upload dist/* ;
+        fi
+  documentation-publish:
+    needs: [build, sonarcloud]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+    - name: Get the current branch name
+      shell: bash
+      run: echo "::set-output name=branch::${GITHUB_REF#refs/heads/}"; echo "Branch Name = ${GITHUB_REF#refs/heads/}"
+      id: branch_name
+    - name: Build documentation only if on release branch
+      working-directory: ./documentation
+      run: |
+        BRANCH_NAME="${{ steps.branch_name.outputs.branch }}"
+        if [[ "${BRANCH_NAME:0:8}" = "release/" ]]; then
+        RELEASE_NAME="${BRANCH_NAME:8}"
+        echo "Release Name: ${RELEASE_NAME}" ;
+        echo "Building Documentation for Release ${RELEASE_NAME}"
+        python -m pip install --user sphinx;
+        python -m pip install --user faculty_sphinx_theme;
+        make html;
+        fi
+

.gitignore

@@ -3,4 +3,5 @@ venv/
 dist/
 build/
 adr_viewer.egg-info/
-.pytest_cache/
+.pytest_cache/
+.DS_Store

.readthedocs.yaml

@@ -0,0 +1,16 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: documentation/source/conf.py

CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [1.3.0](https://pypi.org/project/adr-viewer/1.3.0/) - 2022-02-28
+
+### Added
+- Ignore badly-formed ADR files and report
+- Allow template override and pass in a teplate directory
+- Customizing server port
+
+### Fixed
+- Some typos
+
+### Removed
+- Support for Python 2.7
+
+## [1.2.0](https://pypi.org/project/adr-viewer/1.2.0/) - 2019-06-19
+
+### Added
+- Support for Pending ADRs
+
+## [1.1.1](https://pypi.org/project/adr-viewer/1.1.1/) - 2019-02-26
+
+### Added
+- Python 3 support
+
+
+### Fixed
+- Included HTML file in package
+
+## [1.1.0](https://pypi.org/project/adr-viewer/1.1.0/) - 2018-09-10
+
+### Added
+- Pypi release details
+- Accepted records are green
+- Superceded records are now grey and have their titles struck through
+- Records with unknown state default to white
+- Amended records are yellow
+- Since multiple statuses are possible in ADR files, we now extract all `p` objects below the Status header and use those for deciding on which style to apply
+- Statuses also now represented by icons (colour-blindness)
+- Created and updated this project's ADRs and visualised them
+- Improved `README.md`
+
+## [1.0.1](https://pypi.org/project/adr-viewer/1.0.1/) - 2018-09-02
+
+### Added
+- Classifiers to `setup.py`
+
+
+## [1.0.0](https://pypi.org/project/adr-viewer/1.0.0/) - 2018-09-02
+
+### Initial Release
+

CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to adr-viewer
+
+First of all, thanks for contributing!
+
+This is an evolving document which details what's needed to build and deploy `adr-viewer`.
+Some tasks are only for maintainers, and some are for contributors.
+
+Tasks and information for maintainers are depicted by :large_orange_diamond:
+Tasks and information for contributors are depicted by :large_blue_diamond:
+
+## Contribution Model :large_blue_diamond:
+
+adr-viewer uses the "Gitflow" model (as show in the diagram below). This means that contributors can be working on different branches and features simultaneously, whilst still knowing that there is a path toward production for their contributions, be they code or documentation.
+
+<img src="images/gitflow.png" />
+
+Note that for this model to function correctly, branches must be named accordingly, since the build infrastructure uses these names to determine what to build, and (in some cases) what to deploy and where.
+
+**Branch names**
+| Name | Description | Responsibility |
+|-----|-----|:--:|
+| main | This branch contains the code which is currently in production and therefore deployed to PyPI, and which will be cloned for users to use |  :large_orange_diamond: |
+| hotfix | A hotfix branch is created when a major bug is detected and needs a fix to the production code immediately|:large_orange_diamond: :large_blue_diamond:|
+| release | A release branch is taken when a stable codebase is about to be deployed to production. It must be stable and no further changes can be made to it post-release |:large_orange_diamond: |
+|develop| This branch "collects" all the PRs that have been successfully merged, ready for a release to be cut when ready|:large_orange_diamond: |
+|feature| Feature branches are where new functionality is developed, bug fixes and general updates are carried out prior to being tested and merged into the develop branch|:large_blue_diamond: |
+
+
+**Making a feature change** :large_blue_diamond: :large_orange_diamond:
+
+To allow the change process to proceed smoothly, when making a change, please do the following:
+
+- ensure that you have forked the main repository
+
+All instructions from here onward relate to YOUR copy of the forked repository
+
+- create a new feature branch (e.g. feature/29 - where 29 is the issue number)
+- checkout that branch locally
+- make the change and add any new tests, and make sure the existing tests still pass.
+- add the changed/new/deleted files to the tracked files list (git add xxxxxx)
+- commit the changes with an appropriate message (stating which issue is fixed)
+- push the changes into the repository
+- when you are ready, create a PR into the develop branch
+- collaborate on the review of the PR until the maintainer merges it into the develop branch
+- this PR will then be deployed into the next release
+
+**Secrets and Tokens** :large_orange_diamond:
+
+In order for the build to successfully complete, the following tokens and secrets need to be defined:
+
+SONAR_TOKEN

README.md

@@ -1,6 +1,7 @@
 # adr-viewer
 
-[![Build Status](https://travis-ci.org/mrwilson/adr-viewer.svg?branch=master)](https://travis-ci.org/mrwilson/adr-viewer)
+[![Build Pipeline](https://github.com/mrwilson/adr-viewer/actions/workflows/build-pipeline.yaml/badge.svg)](https://github.com/mrwilson/adr-viewer/actions/workflows/build-pipeline.yaml)
+
 
 Show off your Architecture Decision Records with an easy-to-navigate web page, either as a local web-server or generated static content.
 
@@ -35,11 +36,66 @@ $ python setup.py install
 Usage: adr-viewer [OPTIONS]
 
 Options:
-  --adr-path TEXT  Directory containing ADR files.  [default: doc/adr/]
-  --output TEXT    File to write output to.  [default: index.html]
-  --serve          Serve content at http://localhost:8000/
-  --port INT       Custom server port [default: 8000]
-  --help           Show this message and exit.
+  --adr-path TEXT      Directory containing ADR files.  [default: doc/adr/]
+  --output TEXT        File to write output to.  [default: index.html]
+  --serve              Serve content at http://localhost:8000/
+  --port INTEGER       Change port for the server  [default: 8000]
+  --template-dir TEXT  Template directory.
+  --heading TEXT       ADR Page Heading  [default: ADR Viewer - ]
+  --config TEXT        Configuration settings  [default: config.toml]
+  --help               Show this message and exit.
+```
+
+The configuration file (in [TOML](http://toml.io) format) has settings that control the look of the ADR page. These settings are specifically targetted at the colours of the page to aid with those who have colour-blindness.
+
+The colours (the example used here is `green`) can be specified in a number of formats:
+
+  - Hex values: #00FF00
+  - HTML Colour codes: Green
+  - RGB values: rgb(0,255,0)
+  - RGB with alpha: rgba(0,255,0,0)
+  - HSL values: hsl(0,100%,50%)
+  - HSL with alpha: hsla(0,100%,50%,0)
+
+More information about codes and names for HTML colours can be found [here](http://htmlcolorcodes.com).
+
+The icons for each bar can also be modified using the `.icon` property of each bar. The icon names can be sourced from the [`fontawesome` library's documentation](https://fontawesome.com/v4/icons/).
+
+Note that only ***FREE*** icons are allowed. ***Pro*** icons will not be displayed.
+
+```bash
+# Configuration for adr-viewer
+# in TOML format http://toml.io
+
+title = "TOML Configuration for adr-viewer colours"
+
+[page]
+# Properties for the page
+background-color            = "white"
+
+[status]
+# Properties for the bars that display each ADR 
+
+# Accepted
+accepted.icon               = "fa-check"
+accepted.background-color   = "lightgreen"
+
+# Amended
+amended.icon                = "fa-arrow-down" 
+amended.background-color    = "yellow"
+
+# Pending
+pending.icon                = "fa-hourglass-half"
+pending.background-color    = "lightblue"
+
+# Superseded
+superseded.icon             = "fa-times"
+superseded.background-color = "lightgrey"
+superseded.text-decoration  = "line-through"
+
+# Unknown
+unknown.icon                = "fa-question"
+unknown.background-color    = "white"
 ```
 
 The default for `--adr-path` is `doc/adr/` because this is the default path generated by `adr-tools`.