Merge pull request #10 from PhilippSalvisberg/feature/issue_1

Feature/issue 1

Author: PhilippSalvisberg

.gitignore

@@ -0,0 +1,20 @@
+# macOS internals
+.DS_Store
+
+# NPM-related
+/node_modules
+/npm-debug.log*
+
+# Files generated by build
+/build
+/material/manifest.json
+/MANIFEST
+/site
+/pdf
+
+# Distribution files
+/dist
+/mkdocs_material.egg-info
+
+# temporary files
+~$SQL-and-SQL-Coding-Guidelines.doc

PLSQL-and-SQL-Coding-Guidelines.doc

@@ -2,9 +2,21 @@
 
 ## Introduction
 
-Trivadis published their guidelines for PL/SQL & SQL in 2009 in the context of the DOAG conference in Nuremberg. Since then these guidelines - written in Microsoft Word - have been continuously  extended and improved. We think it is time to make these guidelines more adaptable for the individual #SmartDB application needs and to simplify the continous improvement of these guidelines.
+Trivadis published their guidelines for PL/SQL & SQL in 2009 in the context of the DOAG conference in Nuremberg. Since then these guidelines have been continuously extended and improved. Now they are managed as a set of markdown files. This makes the the guidelines more adaptable for individual application needs and simplifies the continous improvement.
 
-The next step will be to convert the existing guidelines to a set of Markdown files and use Jekyll to generate the guidelines as static HTML files or PDF.
+## HTML format
+
+HTML is the primary output format. [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) is used to generate static HTML files and [Mike](https://github.com/jimporter/mike) to publish version specific variants. The following sites are available:
+
+Link                                                                 | Content
+-------------------------------------------------------------------- | -------
+<https://trivadis.github.io/plsql-and-sql-coding-guidelines/>        | Latest Release
+<https://trivadis.github.io/plsql-and-sql-coding-guidelines/master/> | Current version based on the master branch, typically a snapshot version of the coming release
+<https://trivadis.github.io/plsql-and-sql-coding-guidelines/v3.3/>   | Released version 3.3
+
+## PDF format
+
+PDF is the secondary output format. [wkhtmltopdf](https://wkhtmltopdf.org/) is used to generate the [PLSQL-and-SQL-Coding-Guidelines.pdf](https://raw.githubusercontent.com/Trivadis/plsql-and-sql-coding-guidelines/master/PLSQL-and-SQL-Coding-Guidelines.pdf).
 
 ## Releases
 
@@ -30,4 +42,4 @@ Please file your bug reports, enhancement requests, questions and other support
 
 ## License
 
-The Trivadis PL/SQL & SQL Coding Guidelines is licensed under the Apache License, Version 2.0. You may obtain a copy of the License at <http://www.apache.org/licenses/LICENSE-2.0>.
+The Trivadis PL/SQL & SQL Coding Guidelines are licensed under the Apache License, Version 2.0. You may obtain a copy of the License at <http://www.apache.org/licenses/LICENSE-2.0>.

PLSQL-and-SQL-Coding-Guidelines.pdf

@@ -0,0 +1 @@
+{% extends "base.html" %}

README.md

@@ -0,0 +1,51 @@
+<header class="md-header" data-md-component="header">
+    <nav class="md-header-nav md-grid">
+      <div class="md-flex">
+        <div class="md-flex__cell md-flex__cell--shrink">
+          <a href="{{ config.site_url | default(nav.homepage.url, true) }}" title="{{ config.site_name }}" class="md-header-nav__button md-logo">
+            {% if config.theme.logo.icon %}
+              <i class="md-icon">{{ config.theme.logo.icon }}</i>
+            {% elif config.theme.logo.startswith("http") %}
+              <img src="{{ config.theme.logo }}" height="30">
+            {% else %}
+              <img src="{{ base_url }}/{{ config.theme.logo }}" height="30">
+            {% endif %}
+          </a>
+        </div>
+        <div class="md-flex__cell md-flex__cell--shrink">
+          <label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
+        </div>
+        <div class="md-flex__cell md-flex__cell--stretch">
+          <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
+            {% block site_name %}
+              {% if config.site_name == page.title %}
+                {{ config.site_name }} Version {{ config.extra.guideline_version }}
+              {% else %}
+                <span class="md-header-nav__topic">
+                  {{ config.site_name }} Version {{ config.extra.guideline_version }}
+                </span>
+                <span class="md-header-nav__topic">
+                  {{ page.title }}
+                </span>
+              {% endif %}
+            {% endblock %}
+          </div>
+        </div>
+        <div class="md-flex__cell md-flex__cell--shrink">
+          {% block search_box %}
+            {% if "search" in config["plugins"] %}
+              <label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
+              {% include "partials/search.html" %}
+            {% endif %}
+          {% endblock %}
+        </div>
+        {% if config.repo_url %}
+          <div class="md-flex__cell md-flex__cell--shrink">
+            <div class="md-header-nav__source">
+              {% include "partials/source.html" %}
+            </div>
+          </div>
+        {% endif %}
+      </div>
+    </nav>
+  </header>

custom-theme/main.html

@@ -0,0 +1,36 @@
+FROM centos:7.5.1804
+
+LABEL maintainer="[email protected]"
+LABEL description="Tools to generate HTML and PDF using Materials for MkDocs and wkhtmltopdf."
+LABEL build.command="docker build . --tag trivadis/mktools:latest"
+
+RUN yum install -y https://centos7.iuscommunity.org/ius-release.rpm
+RUN yum update -y
+RUN yum install -y python36u python36u-libs python36u-devel python36u-pip
+RUN yum install -y git
+RUN yum install -y wget
+
+# Install wkhtmltox 0.12.4 since 0.12.5 cannot create TOCs, see https://github.com/wkhtmltopdf/wkhtmltopdf/issues/3995
+# RUN yum install -y https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.5/wkhtmltox-0.12.5-1.centos7.x86_64.rpm
+RUN yum install -y yum install -y wkhtmltopdf
+RUN wget -q https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.4/wkhtmltox-0.12.4_linux-generic-amd64.tar.xz -O /tmp/wkhtmltox.tar.xz && \
+    tar xvf /tmp/wkhtmltox.tar.xz -C /tmp && \
+    cp -rp /tmp/wkhtmltox/* /usr/local && \
+    rm -rf /tmp/wkhtmltox*
+
+RUN pip3.6 install --upgrade pip
+RUN pip3.6 install mkdocs \
+                   mkdocs-material \
+                   mkdocs-awesome-pages-plugin \
+                   pymdown-extensions \
+                   mike 
+
+ENV LC_ALL=en_US.utf8
+ENV LANG=en_US.utf8
+
+# volume for GitHub project's root folder containing docs folder  
+RUN mkdir /data
+VOLUME ["/data"]
+
+# port for mkdocs serve
+EXPOSE 8000

custom-theme/partials/header.html

@@ -0,0 +1 @@
+collapse_single_pages: true

docker/Dockerfile

@@ -0,0 +1,68 @@
+# Introduction
+
+This document describes rules and recommendations for developing applications using the PL/SQL & SQL Language. 
+
+## Scope
+
+This document applies to the PL/SQL and SQL language as used within ORACLE databases and tools, which access ORACLE databases.
+
+## Document Conventions
+
+SQALE (Software Quality Assessment based on Lifecycle Expectations) is a method to support the evaluation of a software application source code. It is a generic method, independent of the language and source code analysis tools.
+
+### SQALE characteristics and subcharacteristics
+
+Characteristic | Description and Subcharacteristics
+-------------- | ----------------------------------
+Changeability  | The capability of the software product to enable a specified modification to be implemented.<ul><li>Architecture related changeability</li><li>Logic related changeability</li><li>Data related changeability</li><ul>
+Efficiency | The capability of the software product to provide appropriate performance, relative to the amount of resources used, under stated conditions.<ul><li>Memory use</li><li>Processor use</li><li>Network use</li></ul>
+Maintainability | The capability of the software product to be modified. Modifications may include corrections, improvements or adaptation of the software to changes in environment, and in requirements and functional specifications.<ul><li>Understandability</li><li>Readability</li></ul>
+Portability | The capability of the software product to be transferred from one environment to another.<ul><li>Compiler related portability</li><li>Hardware related portability</li><li>Language related portability</li><li>OS related portability</li><li>Software related portability</li><li>Time zone related portability.</li></ul>
+Reliability | The capability of the software product to maintain a specified level of performance when used under specified conditions.<ul><li>Architecture related reliability</li><li>Data related reliability</li><li>Exception handling</li><li>Fault tolerance</li><li>Instruction related reliability</li><li>Logic related reliability</li><li>Resource related reliability</li><li>Synchronization related reliability</li><li>Unit tests coverage.</li></ul>
+Reusability | The capability of the software product to be reused within the development process.<ul><li>Modularity</li><li>Transportability.</li></ul>
+Security | The capability of the software product to protect information and data so that unauthorized persons or systems cannot read or modify them and authorized persons or systems are not denied access to them.<ul><li>API abuse</li><li>Errors (e.g. leaving a system in a vulnerable state)</li><li>Input validatation and representation</li><li>Security features.</li></ul>
+Testability | The capability of the software product to enable modified software to be validated.<ul><li>Integration level testability</li><li>Unit level testability.</li></ul>
+
+### Severity of the rule
+
+!!! bug "Blocker"
+    Will or may result in a bug.
+
+!!! danger "Critical"
+    Will have a high/direct impact on the maintenance cost.
+
+!!! warning "Major"
+    Will have a medium/potential impact on the maintenance cost.
+
+!!! tip "Minor"
+    Will have a low impact on the maintenance cost.
+
+!!! info "Info"
+    Very low impact; it is just a remediation cost report.
+
+### Keywords used
+
+Keyword     | Meaning
+----------- | -------
+Always      | Emphasizes this rule must be enforced.
+Never       | Emphasizes this action must not happen.
+Avoid       | Emphasizes that the action should be prevented, but some exceptions may exist.
+Try         | Emphasizes that the rule should be attempted whenever possible and appropriate.
+Example     | Precedes text used to illustrate a rule or a recommendation.
+Reason      | Explains the thoughts and purpose behind a rule or a recommendation.
+Restriction | Describes the circumstances to be fulfilled to make use of a rule.
+
+### Why are standards important
+
+For a machine executing a program, code formatting is of no importance. However, for the human eye, well-formatted code is much easier to read. Modern tools can help to implement format and coding rules.
+
+Implementing formatting and coding standards has the following advantages for PL/SQL development:
+
+* Well-formatted code is easier to read, analyze and maintain (not only for the author but also for other developers).
+* The developers do not have to define their own guidelines - it is already defined.
+* The code has a structure that makes it easier to avoid making errors.
+* The code is more efficient concerning performance and organization of the whole application.
+* The code is more modular and thus easier to use for other applications.
+
+This document only defines possible standards. These standards are not written in stone, but are meant as guidelines. If standards already exist, and they are different from those in this document, it makes no sense to change them.
+ 

docs/1-introduction/.pages

@@ -0,0 +1 @@
+collapse_single_pages: true