Added: MkDocs documentation and readthedocs.io configuration (#856)

Fixes #853

.editorconfig

@@ -0,0 +1,18 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+indent_size = 4
+
+[Makefile]
+indent_style = tab

.github/CONTRIBUTING.md

@@ -1,50 +1,64 @@
-Contributing to Goss
-====================
+# Contributing to Goss
 
-Thank you for your interest in contributing to Goss. Goss wouldn't be where it is today if it wasn't for people like you. Some ways you can contribute:
+Thank you for your interest in contributing to Goss. Goss wouldn't be where it is today if it wasn't for people like you.
+Some ways you can contribute:
 
-* Improve the [README](https://github.com/goss-org/goss/blob/master/README.md) and/or [Docs](https://github.com/goss-org/goss/blob/master/docs/manual.md) - This makes it easier for new users to learn goss.
+* Improve the [README](https://github.com/goss-org/goss/blob/master/README.md)
+    and/or [Docs](https://github.com/goss-org/goss/blob/master/docs/).
+    This makes it easier for new users to learn goss.
 * Vote on bugs and feature requests by adding a :+1: reaction to the inital post.
 * Create tutorials, blog posts and example use-cases on how to use Goss.
 * Help users with [questions](https://github.com/goss-org/goss/labels/question) tracker.
 * Fix verified [bugs](https://github.com/goss-org/goss/issues?q=is%3Aopen+is%3Aissue+label%3Aapproved+label%3Abug+sort%3Areactions-%2B1-desc).
 * Implement approved [feature requests](https://github.com/goss-org/goss/issues?q=is%3Aopen+is%3Aissue+label%3Aapproved+label%3Aenhancement+sort%3Areactions-%2B1-desc).
 * Spread the word.
 
+## Features and bug reports and questions
 
-Features and bug reports and questions
---------------------------------------
+Please search the [issues](https://github.com/goss-org/goss/issues) page before opening a feature request or a bug report.
+If a feature or a bug report already exists,
+please thumbs up the initial post to indicate it's importance to you and raise it's priority.
+Please comment and contribute to said issue if you feel it's deficient.
 
-Please search the [issues](https://github.com/goss-org/goss/issues) page before opening a feature request or a bug report. If a feature or a bug report already exists, please thumbs up the initial post to indicate it's importance to you and raise it's priority. Please comment and contribute to said issue if you feel it's deficient.
-
-Bug reports
------------
+## Bug reports
 
 If you think you found a bug in Goss, please submit a [bug report](https://github.com/goss-org/goss/issues).
 
-Feature requests
-----------------
+## Feature requests
 
 If there's a feature you wish Goss would support, please open a feature request.
 
 Some things to note prior to opening a Goss feature request:
-* Goss is intended to be quick and easy to learn.
-* Goss is focused on the 20% of the 80/20 rule. In other words, Goss focuses on the 20% of features that cover the core aspects of OS testing and benefit 80% of users.
-* Goss is intended to test the local machine it's running on. Tests aren't intended to be used to validate remote systems or endpoints.
-* Goss provides a generic [command](https://github.com/goss-org/goss/blob/master/docs/manual.md#command) runner to allow users to cover more nuanced test cases.
 
-If you believe your feature adheres to the goals of Goss, please open a [feature request](https://github.com/goss-org/goss/issues) on GitHub which describes the feature you would like to see, why it is useful, and how it should work.
+* Goss is intended to be quick and easy to learn.
+* Goss is focused on the 20% of the 80/20 rule.
+    In other words, Goss focuses on the 20% of features that cover the core aspects of OS testing and benefit 80% of users.
+* Goss is intended to test the local machine it's running on.
+    Tests aren't intended to be used to validate remote systems or endpoints.
+* Goss provides a generic [command](https://goss.rocks/gossfile/#command) runner
+    to allow users to cover more nuanced test cases.
 
-Once a feature is submitted, it will be reviewed. Upon approval, the issue can be worked on and PRs can be submitted that implement this new feature.
+If you believe your feature adheres to the goals of Goss,
+please open a [feature request](https://github.com/goss-org/goss/issues) on GitHub
+which describes the feature you would like to see, why it is useful, and how it should work.
 
+Once a feature is submitted, it will be reviewed.
+Upon approval, the issue can be worked on and PRs can be submitted that implement this new feature.
 
-Contributing code and documentation changes
--------------------------------------------
+## Contributing code and documentation changes
 
-If you have a bugfix or new feature that you would like to contribute to Goss, please find or open an issue about it first. Talk about what you would like to do. It may be that somebody is already working on it, or that there are particular issues that you should know about before implementing the change.
+If you have a bugfix or new feature that you would like to contribute to Goss, please find or open an issue about it first.
+Talk about what you would like to do. It may be that somebody is already working on it,
+or that there are particular issues that you should know about before implementing the change.
 
-We enjoy working with contributors to get their code accepted. There are many approaches to fixing a problem and it is important to find the best approach before writing too much code.
+We enjoy working with contributors to get their code accepted.
+There are many approaches to fixing a problem and it is important to find the best approach before writing too much code.
 
-Note that it is unlikely the project will merge refactors for the sake of refactoring or niche features that aren't common use-cases (see the feature request section above). These types of pull requests have a high cost to maintainers but provide little benefit to the community.
+Note that it is unlikely the project will merge refactors for the sake of refactoring
+or niche features that aren't common use-cases (see the feature request section above).
+These types of pull requests have a high cost to maintainers but provide little benefit to the community.
 
-Lastly, in order for a pull request to be merged, it must provide automated tests (unit and/or integration) proving the change works as intended, this also prevents future changes from introducing regressions. It would be quite odd for a testing tool to not have a healthy approach to test automation, after all. :-)
+Lastly, in order for a pull request to be merged,
+it must provide automated tests (unit and/or integration) proving the change works as intended,
+this also prevents future changes from introducing regressions.
+It would be quite odd for a testing tool to not have a healthy approach to test automation, after all. :smile:

.github/ISSUE_TEMPLATE/feature_request.md

@@ -11,7 +11,7 @@ assignees: ''
 Some things to note prior to opening a Goss feature request:
 * Goss is intended to be quick and easy to learn.
 * Goss is focused on the 20% of the 80/20 rule. In other words, Goss focuses on the 20% of features that cover the core aspects of OS testing and benefit 80% of users.
-* Goss provides a generic [command](https://github.com/goss-org/goss/blob/master/docs/manual.md#command) runner to allow users to cover more nuanced test cases.
+* Goss provides a generic [command](https://goss.rocks/gossfile/#command) runner to allow users to cover more nuanced test cases.
 
 If after reading the above, you believe your feature is valid within the project scope please submit this feature request.
 

.github/workflows/docs.yaml

@@ -0,0 +1,47 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    paths:
+      - mkdocs.yml
+      - docs/
+      - README.md
+      - LICENSE
+      - extras/**/README.md
+      - .github/CONTRIBUTING.md
+  workflow_dispatch:
+
+jobs:
+  lint:
+    name: Lint Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DavidAnson/markdownlint-cli2-action@v13
+        with:
+          globs: |
+            docs/**/*.md
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+          cache: 'pip'
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install --requirement docs/requirements.pip
+      - name: Build documentation
+        run: mkdocs build
+      # To remove if not using github pages
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: site

.github/workflows/preview-docs.yaml

@@ -0,0 +1,23 @@
+name: Preview documentation
+on:
+  pull_request_target:
+    types:
+      - opened
+    paths:
+      - mkdocs.yml
+      - docs/
+      - README.md
+      - LICENSE
+      - extras/**/README.md
+      - .github/CONTRIBUTING.md
+
+jobs:
+  pull-request-links:
+    name: Add preview link to pull-request
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: goss

.gitignore

@@ -17,3 +17,9 @@ tmp/
 
 /c.out
 /c.out.tmp
+
+# Documentation
+## Virtualenv
+/.venv
+## MkDocs rendered site
+/site

.markdownlint.yaml

@@ -0,0 +1,41 @@
+---
+# Enable all rules
+default: true
+
+# Enforce asterisk for unordered lists
+# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/md004.md
+MD004:
+  style: asterisk
+
+# Set list indent level to 4 which Python-Markdown requires
+# See:
+#  - https://github.com/DavidAnson/markdownlint/blob/main/doc/md007.md
+#  - https://python-markdown.github.io/#differences
+MD007:
+  indent: 4
+
+# Tune `line-length`
+# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md
+MD013:
+  line_length: 120
+  tables: false
+  code_blocks: false
+
+# Disable `blanks-around-list` (to stay close from GitHub-flavored markdown)
+# See:
+#  - https://github.com/DavidAnson/markdownlint/blob/main/doc/md032.md
+#  - https://python-markdown.github.io/#differences
+MD032: false
+
+# Disable `no-space-in-code`
+# Generate lots of false positive with admonitions and code blocks
+MD038: false
+
+# Disable `code-blocks-style`
+# Use fenced code blocks everywhere but raise false positives with admonitions
+MD046: false
+
+# Disable `link-fragments`
+# Only works for github-rendered markdown (which does not have the same rules as MkDocs)
+# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md
+MD051: false

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration file for MkDocs projects
+# 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-22.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+  - requirements: docs/requirements.pip

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright {yyyy} {name of copyright owner}
+   Copyright 2015 Ahmed Elsabbahy
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -199,4 +199,3 @@
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-

Makefile

@@ -5,6 +5,9 @@ pkgs = $(shell ./novendor.sh)
 cmd = goss
 GO111MODULE=on
 GO_FILES = $(shell git ls-files -- '*.go' ':!:*vendor*_test.go')
+VENV := $(shell echo $${VIRTUAL_ENV-.venv})
+PYTHON := $(VENV)/bin/python
+DOCS_DEPS := $(VENV)/.docs.dependencies
 
 .PHONY: all build install test release bench fmt lint vet test-int-all gen centos7 wheezy trusty alpine3 arch test-int32 centos7-32 wheezy-32 trusty-32 alpine3-32 arch-32
 
@@ -73,6 +76,8 @@ gen:
 clean:
 	$(info INFO: Starting build $@)
 	rm -rf ./release
+	rm -rf ./site
+	rm -rf ${VENV}
 
 build-images:
 	$(info INFO: Starting build $@)
@@ -130,3 +135,24 @@ arch: build
 
 dgoss-sha256:
 	cd extras/dgoss/ && sha256sum dgoss > dgoss.sha256
+
+$(PYTHON):
+	$(info Creating virtualenv in $(VENV))
+	@python -m venv $(VENV)
+
+$(DOCS_DEPS): $(PYTHON) docs/requirements.pip
+	$(info Installing dependencies)
+	@pip install --upgrade pip
+	@pip install --requirement docs/requirements.pip
+	@touch $(DOCS_DEPS)
+
+docs/setup: $(DOCS_DEPS)
+
+docs/serve: docs/setup
+	$(info Running documentation live development server)
+	@mkdocs serve --strict
+
+.PHONY: docs
+docs: docs/setup
+	$(info Building documentation)
+	@mkdocs build --strict