build docs on release (#3)

Author: drsm79

.github/workflows/documentation.yml

@@ -0,0 +1,33 @@
+name: docs
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build_documentation:
+    name: Generate documentation
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.7'
+    - name: Install dependencies
+      run: |
+        make install
+        make develop
+    - name: Prep branch
+      run: git worktree add $TMPDIR/af-gh-pages gh-pages
+    - name: Build documentation
+      run: |
+        make docs DOC_TARGET=$TMPDIR/af-gh-pages
+    - name: Commit docs
+      run: |
+        cd $TMPDIR/af-gh-pages
+        git add *
+        git commit -a -m 'Documentation update for release' --no-verify
+        git push origin gh-pages

Makefile

@@ -14,6 +14,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+DOC_TARGET?=doc
+
 develop:
 	pip install -q -e .[dev] --upgrade --upgrade-strategy eager
 	pre-commit install
@@ -38,4 +40,4 @@ test::
 docs:
 	# Build the API docs from the source code - overwrites those files, which are ignored by git
 	sphinx-apidoc -o doc-source compliance
-	sphinx-build doc-source doc
+	sphinx-build doc-source $(DOC_TARGET)

doc-source/conf.py

@@ -3,14 +3,12 @@
 import os
 import sys
 import datetime
-import compliance
 
-sys.path.insert(
-    0,
-    os.path.abspath(os.path.join(os.path.dirname(__file__), '../compliance'))
-)
+new_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
+sys.path.insert(0, new_path)
 
-print(os.path.abspath(os.path.join(os.path.dirname(__file__), '../compliance')))
+import compliance
+print(new_path)
 
 # -- General configuration ------------------------------------------------
 

doc-source/credentials-example.cfg

@@ -1,7 +1,7 @@
 # -*- mode:conf -*-
 
-# Token for github.ibm.com to be used by the Locker
-[github_enterprise]
+# Token for github.com to be used by the Locker
+[github]
 token=XXX
 
 # Webhook for Slack notifications

doc-source/design-principles.rst

@@ -62,13 +62,13 @@ for:
 
     {
       "locker": {
-        "repo_url": "https://github.ibm.com/my-org/my-evidence",
+        "repo_url": "https://github.com/my-org/my-evidence-repo",
         "gitconfig": {
           "commit": {"gpgsign": true},
           "gpg": {"program": "gpg2"},
           "user": {
             "signingKey": "AABBCCDD",
-            "email": "compliance-robot@ibm.com",
+            "email": "compliance-robot@my-org.com",
             "name": "compliance-robot"
           }
         }
@@ -93,7 +93,7 @@ for:
 
    {
      "locker": {
-       "repo_url": "https://github.ibm.com/my-org/my-evidence",
+       "repo_url": "https://github.com/my-org/my-evidence-repo",
        "ttl_tolerance": 3600
      }
    }
@@ -425,15 +425,7 @@ levels:
 Credentials
 ~~~~~~~~~~~
 
-The compliance tool uses the `utilitarian
-<https://github.ibm.com/cloudant/utilitarian>`_ library for managing
-credentials. Fetchers and checks might need to use credentials in
-order to access different resources on different locations. The tool
-assumes that there is a file at ``~/.credentials`` and the sections and
-fields supported are defined by
-:py:class:`utilitarian.crendentials.Config`.
-
-If you want to configure your credentials locally, the compliance tool
+If you want to configure your credentials locally, the framework
 will look for a credentials file at ``~/.credentials`` by default. This
 file should be similar to this:
 

doc-source/evidence-partitioning.rst

@@ -6,10 +6,10 @@ Partitioned Evidence
 ====================
 
 Depending on the repository hosting service being used, it may be necessary to
-manage evidence more effectively.  For example Github Enterprise will not allow
-pushing files larger than 100MB.  In cases like this it is possible to
-partition evidence into smaller, more manageable chunks if that evidence
-satisfies the following conditions:
+manage evidence more effectively.  For example Github has limits on individual
+file sizes.  In cases like this it is possible to partition evidence into
+smaller, more manageable chunks if that evidence satisfies the following
+conditions:
 
 * Evidence is of the type :py:class:`~compliance.evidence.RawEvidence` or a
   sub-class of :py:class:`~compliance.evidence.RawEvidence`.
@@ -44,7 +44,7 @@ where the evidence will be partitioned.  For example::
 
   {
     "locker": {
-      "repo_url": "https://github.ibm.com/my-org/my-repo",
+      "repo_url": "https://github.com/my-org/my-evidence-repo",
       "partitions": {
         "foo/evidence_bar.json": {
           "fields": ["location.country", "location.region"],
@@ -58,7 +58,7 @@ or::
 
   {
     "locker": {
-      "repo_url": "https://github.ibm.com/my-org/my-repo",
+      "repo_url": "https://github.com/my-org/my-evidence-repo",
       "partitions": {
         "foo/evidence_bar.json": {
           "fields": ["location.country", "location.region"]
@@ -120,7 +120,7 @@ Default Partition Root
 
     {
       "locker": {
-        "repo_url": "https://github.ibm.com/my-org/my-repo",
+        "repo_url": "https://github.com/my-org/my-evidence-repo",
         "partitions": {
           "foo/evidence_bar.json": {
             "fields": ["country", "region"]
@@ -174,7 +174,7 @@ Explicit Partition Root
 
     {
       "locker": {
-        "repo_url": "https://github.ibm.com/my-org/my-repo",
+        "repo_url": "https://github.com/my-org/my-evidence-repo",
         "partitions": {
           "foo/evidence_bar.json": {
             "fields": ["country", "region"],

doc-source/index.rst

@@ -1,28 +1,22 @@
 .. -*- mode:rst; coding:utf-8 -*-
 
-compliance-tool's documentation
-===============================
+Auditree framework documentation
+================================
 
 Tool to run compliance control checks as unit tests.
 
-`#compliance-tooling <https://ibm-cloudplatform.slack.com/messages/C3X0P7CUB>`_
-
 Installation
 ------------
 
 For users
 ~~~~~~~~~
 
-You can use the following ``pip`` command for installing
-``compliance-tool`` in your environment. The URL is also suitable for
-``requirements.txt`` and ``setup.py`` (using ``setuptools``)::
-
-  $ pip install git+ssh://git@github.ibm.com/clouddataservices/compliance-tool.git#egg=compliance-tool
+The framework is uploaded to `pypi <https://pypi.org/project/auditree-framework/>`_.
+You can install it via:
 
+.. code-block:: bash
 
-You can specify a specific version. For example ``v0.0.1``::
-
-  $ pip install git+ssh://git@github.ibm.com/clouddataservices/compliance-tool.git@v0.0.1#egg=compliance-tool
+   $ pip install auditree-framework
 
 See the :ref:`quick-start` section for a brief introduction to the
 tool usage. Also, see :ref:`running-on-travis` section for getting
@@ -33,12 +27,11 @@ For developers
 
 .. code-block:: bash
 
-   $ git clone git@github.ibm.com:cloumpose/compliance-tool
-   $ cd compliance-tool
-   $ git submodule update --init --recursive
-   $ virtualenv --no-site-packages venv
+   $ git clone git@github.com:ComplianceAsCode/auditree-framework.git
+   $ cd auditree-framework
+   $ python3 -m venv venv
    $ . venv/bin/activate
-   $ make develop
+   $ make install && make develop
 
 Guides
 ------

doc-source/notifiers.rst

@@ -5,12 +5,13 @@
 Notifiers
 =========
 
-The last phase in a typical compliance-tool check run is the notification
+The last phase in a typical framework check run is the notification
 system.  Multiple notifiers can be targeted as part of this phase  by using
 the ``--notify`` option on the ``compliance --check`` command.  Valid
-notifier options are ``stdout``, ``slack``, ``pagerduty``, ``ghe_issues`` and,
-``locker``.  The general idea behind the notification system is that each
-``test_`` can generate a short notification that has the following components:
+notifier options are ``stdout``, ``slack``, ``pagerduty``, ``findings``,
+``gh_issues`` and, ``locker``.  The general idea behind the notification
+system is that each ``test_`` can generate a short notification that has the
+following components:
 
 * title (mandatory): should be a ``property`` of the
   ``ComplianceCheck``:
@@ -56,7 +57,7 @@ warnings, the number of issues fixed by fixers (if applicable), links to report
 evidences generated (if applicable) and a link to the check runbook that
 contains remediation instructions (if applicable).
 
-The following sections describe the notifiers supported by the compliance-tool.
+The following sections describe the notifiers supported by the framework.
 
 File descriptor
 ---------------
@@ -144,26 +145,26 @@ Channel ID ``11223344`` can be obtained quickly from the URL to a
 message of the target private channel. Of course, the Slack App needs
 to be part of the private channel.
 
-GitHub Enterprise Issue
------------------------
+GitHub Issue
+------------
 
 Depending on the configuration this notifier will create or update a GitHub
 issue per check or as a summary issue per accreditation. If an open issue
 already exists then the notification will be added to the existing issue as
 an issue comment otherwise a new issue will be created.
 
 This notifier needs to know the credentials for interacting with the provided
-GitHub Enterprise repositories.  Your credentials should, at a minimum, have
+GitHub repositories.  Your credentials should, at a minimum, have
 ``write`` access to all repositories specified for notifications to function
-correctly. Provide your GitHub Enterprise id and personal access token in your
+correctly. Provide your GitHub id and personal access token in your
 credentials file as shown below::
 
-  [github_enterprise]
-  username=my-ghe-id
-  token=my-ghe-personal-access-token
+  [github]
+  username=my-gh-id
+  token=my-gh-personal-access-token
 
-GHE Summary Issue by Accreditation
-**********************************
+GH Summary Issue by Accreditation
+*********************************
 
 A configuration element for each accreditation is necessary to send summary
 issue notifications using this notifier. Summary notifications send all
@@ -172,8 +173,8 @@ configuration should consist of a list of repositories to send the notifications
 to, optionally a project and column to assign your notification to, along
 with a "summary_issue" sub-document dictionary that is used by the notifier to
 configure the summary issue.  To specify a repository provide the GitHub
-Enterprise "owner" and "repository" in the form of ``owner/repository``.
-The "summary_issue" can be configured with the following fields:
+"owner" and "repository" in the form of ``owner/repository``. The "summary_issue"
+can be configured with the following fields:
 
 - "title"
    - Required
@@ -206,11 +207,11 @@ The "summary_issue" can be configured with the following fields:
      upon creation
 - "assignees"
    - Optional
-   - List of strings (GHE user IDs)
+   - List of strings (GH user IDs)
    - Assigns the issue to the list of users
 - "rotation"
    - Optional
-   - List of lists of strings (GHE user IDs)
+   - List of lists of strings (GH user IDs)
    - The "frequency" is required when setting a rotation
    - When present with "frequency", overrides the "assignees" setting
    - Assigns the issue to the list of users based on the frequency and order
@@ -222,7 +223,7 @@ compliance checks::
 
   {
     "notify": {
-      "ghe_issues": {
+      "gh_issues": {
         "accr1": {
           "repo": ["my-org/accr1-repo"],
           "project": {"Super cool project": "Triage"},
@@ -242,15 +243,15 @@ compliance checks::
     }
   }
 
-GHE Issue Per Check
-*******************
+GH Issue Per Check
+******************
 
 A configuration element for each accreditation is necessary to send
 notifications per check using this notifier.  Each accreditation configuration
 should consist of a list of repositories to send the notifications to, a
 list of check execution statuses to send notifications for, and optionally a
 list of projects boards and project columns to add the notification issues to.
-To specify a repository provide the GitHub Enterprise "owner" and "repository"
+To specify a repository provide the GitHub "owner" and "repository"
 in the form of ``owner/repository``.  Valid status values include "pass",
 "warn", "fail", and "error".  If no status configuration is provided then the
 "fail" status is used as the default.  Finally to specify project boards to
@@ -261,7 +262,7 @@ with the ``-C`` option when executing your compliance checks::
 
   {
     "notify": {
-      "ghe_issues": {
+      "gh_issues": {
         "accr1": {
           "repo": ["my-org/accr1-repo"],
           "project": {"Super cool project": "Triage"},

doc-source/quick-start.rst

@@ -48,10 +48,10 @@ You might want to push the evidences generated by ``--fetch`` into a
 remote git repository. For that, you can use ``--evidence`` and ``-C
 setup.json``. This ``setup.json`` contains a fake URL of the repo, you
 can edit it to match the URL you want. However, you have to provide
-GitHub Enterprise credentials. By default, you should use
+GitHub credentials. By default, you should use
 ``~/.credentials`` (or use ``--creds-path`` to point somewhere else)::
 
-  [github_enterprise]
+  [github]
   token=XXX
 
 Once you have set it up, you can run the fetchers in ``no-push``