Merge branch '85-add-gitlab-ci-templates' into 'master'

Add CI templating for hugo docs and update documentation appropriately.

See merge request consensus.enterprises/drumkit!38

docs/content/development/contribute.md

@@ -45,3 +45,12 @@ Drumkit is designed to gather all the necessary binaries for a particular projec
 At this point, you will be able to make changes to the files inside drumkit (below the `.mk` folder) and push them to the drumkit repo.
 
 However, most of the impacts of using Drumkit occur at the root directory, so there is an additional layer of abstraction to consider. 
+
+#### Common points of failure
+
+When [testing](testing), for example, you need to remain aware of whether you are calling certain things (behat features, for example) from the project directory or from the `.mk` directory. Additionally, you need to keep the submodule and the project in sync. 
+
+If you make changes to the `.mk` directory and then commit them in the containing project, you must push the `.mk` branch before pushing changes to the project, or the CI process is likely to fail, being unable to retrieve the correct commit of the Drumkit project.
+
+
+

docs/content/development/testing.md

@@ -15,4 +15,14 @@ You can test the installation by running `behat` (it just checks for correct ins
 
 To run the tests specific to the component you are developing, navigate to `.mk` and run `behat {filename}` for the component. For example, to run the tests for the hugo project, run `behat features/projects/hugo-docs.feature`
 
-These are the tests most likely to break and fail when you push a change, so they should be run locally before pushing to the repo. The CI process runs the complete behat suite on all branches, so this is the quickest way to prevent pipeline failures.
+These are the tests most likely to break and fail when you push a change, so they should be run locally before pushing to the repo. The CI process (when you push changes to the [drumkit project](https://gitlab.com/consensus.enterprises/drumkit) on gitlab) runs the complete `behat` suite on any branch, not just master. Running the tests locally before pushing changes is a relatively easy way to prevent pipeline failures.
+
+This is not to say that you won't have pipeline failures; it will just catch the ones that break any tests associated with the code you just wrote.
+
+## Testing the output from Drumkit
+
+The ultimate test of Drumkit is that it pushes working code to the (surrounding/containing) project you are working on with it.
+
+Process:
+If you are developing Drumkit, per se, you should test and push the project as well as the drumkit code. This ensures that any modifications we make to (for example) `.gitlab-ci.yml` templates produces the correct files in the end.
+

docs/content/usage/hugo-docs.md

@@ -33,4 +33,6 @@ The deployment to Gitlab Pages is managed automatically by the `.gitlab-ci.yml`
 
 At the bottom of the file, under `pages`, the `publish` stage will run `hugo` in the docs folder, which generates a set of static HTML files in the `public` folder, which is then made available through Gitlab pages.
 
-The address at Gitlab Pages will be `http://<GITLAB_GROUP>.gitlab.io/<GITLAB_PROJECT_NAME>/`
+The address at Gitlab Pages will be `http://<GITLAB_GROUP>.gitlab.io/<GITLAB_PROJECT_NAME>/`
+
+To set up your Gitlab Pages, you need to update the configuration in `docs/config.yaml`, which is set to "http://mygroup.gitlab.io/myproject". 

files/hugo-docs/.gitlab-ci.yml.tmpl

@@ -22,10 +22,12 @@ pages:
   script:
   - make hugo
   - . d
-  - hugo
+  - mkdir public
+  - cd docs && hugo
+  - mv public ..
   artifacts:
     paths:
     - public
   only:
-  - master
+  - main
 

files/hugo-docs/config.yaml.tmpl

@@ -1,6 +1,12 @@
 # To configure this for deployment to gitlab pages, replace "mygroup" with your group name
 # and replace all instances of "myproject" with the name of the project.
 
+# Note : You may be tempted to change "mygroup" and "myproject" to 
+# "<GITLAB_GROUP>" or "{{GITLAB_GROUP}}" in the template. *** Don't. *** 
+# There is a format checker at some point that breaks 
+# the entire process. I've forgotten exactly where. (SLD March 2021)
+
+
 baseUrl: "http://mygroup.gitlab.io/myproject/"
 languageCode: "en-US"
 defaultContentLanguage: "en"