Merge pull request #34 from JohnStrunk/initial_docs

Add initial documentation for readthedocs

.travis.yml

@@ -16,3 +16,9 @@ jobs:
         - gem install asciidoctor mdl
         - pip install yamllint
       script: scripts/pre-commit.sh --require-all
+    - stage: linters
+      name: Documentation linter
+      language: python
+      install:
+        - pip install mkdocs
+      script: mkdocs build

README.md

@@ -1,6 +1,7 @@
 # Gluster operator for Kubernetes and OpenShift
 
 [![Build Status](https://travis-ci.org/gluster/anthill.svg?branch=master)](https://travis-ci.org/gluster/anthill)
+[![Documentation Status](https://readthedocs.org/projects/gluster-anthill/badge/?version=latest)](http://gluster-anthill.readthedocs.io/)
 <!-- Badges: TravisCI, CentOS CI, Coveralls, GoDoc, GoReport, ReadTheDocs -->
 
 **Found a bug?** [Let us know.](https://github.com/gluster/operator/issues/new?template=bug_report.md)

docs/Developers/Editing_the_documentation.md

@@ -0,0 +1,50 @@
+# Editing the documentation
+
+The documentation resides in the main Anthill repo, under the `/docs`
+directory as a set of markdown files.
+
+Documentation is checked as a part of the Travis CI infrastructure, but it is
+actually build directly by ReadTheDocs, triggered by a webhook upon commit.
+
+If you are making changes to the documentation or its configuration, you
+probably want to edit and view your changes locally. This can be done
+relatively easily using `mkdocs`.
+
+## Building locally
+
+The mkdocs tool can be installed via pip:
+
+```sh
+pip install mkdocs
+```
+
+You can then view live updates as you make documentation changes by starting
+the documentation server.
+
+From the top directory of this repo:
+
+```sh
+mkdocs serve
+```
+
+By default, this will start a web server on your local machine, allowing you to
+view the documentation by pointing your browser at:
+[https://localhost:8000](https://localhost:8000)
+
+## Documentation hints
+
+The placement of the markdown files and how they are named affect the layout of
+the documentation site. Some things to keep in mind:
+
+- The menu bar across the top has an entry for each markdown file in the top
+  `/docs` directory. It also has a drop-down for each directory that contains
+  markdown files.
+- Menus (top and dropdown) are sorted alphabetically by the name of the file.
+- File names become the entries in the menus. Case is preserved, and
+  underscores become spaces.
+- Each page has its outline displayed on the left.
+- Links within the documentation should be relative links to the `*.md` source
+  file. The documentation builder will make it point to the correct place.
+
+For more information, check out the documentation at
+[MkDocs](https://www.mkdocs.org/).

docs/Developers/Testing_and_validation.md

@@ -0,0 +1,48 @@
+# Testing and validation
+
+This page provides an overview of the project's testing infrastructure.
+
+## Git pre-commit hook
+
+The scripts directory has a script that can be used as a git pre-commit hook to
+lint your files prior to committing. While this is totally optional, our CI
+infrasturcture will run it and fail your PR if it doesn't pass cleanly.
+
+You can run the script manually:
+
+```sh
+$ ./scripts/pre-commit.sh
+
+mdl ./.github/ISSUE_TEMPLATE/bug_report.md
+mdl ./.github/ISSUE_TEMPLATE/feature_request.md
+mdl ./.github/pull_request_template.md
+mdl ./docs/index.md
+mdl ./docs/Developers/Testing_and_validation.md
+mdl ./docs/Developers/Editing_the_documentation.md
+mdl ./docs/Users_guide/index.md
+mdl ./CONTRIBUTING.md
+mdl ./README.md
+shellcheck ./scripts/pre-commit.sh
+yamllint -s ./.travis.yml
+yamllint -s ./mkdocs.yml
+ALL OK.
+```
+
+Optionally, you can install it to run automatically each time you `git commit`.
+To install the hook, create a link to the script in your local `.git/hooks`
+directory:
+
+```sh
+cd .git/hooks
+ln -s ../../scripts/pre-commit.sh pre-commit
+```
+
+## CI infrastructure
+
+The project makes use of Travis CI for linting (and soon, unit testing).
+
+A check by Travis (see `.travis.yml`) is invoked with each commit and PR.
+Currently, it:
+
+- runs the pre-commit.sh script to lint all formatted files
+- runs mkdocs to ensure the documentation builds cleanly

docs/Users_guide/index.md

@@ -0,0 +1,4 @@
+# User documentation
+
+For now, there's not much to use. Check back later when we have something you
+can install.

docs/index.md

@@ -0,0 +1,10 @@
+# Main
+
+Anthill is a [Kubernetes](https://kubernetes.io) operator that manages
+[Gluster](https://gluster.org) storage clusters.
+
+## Quickstart
+
+You're done!
+
+Also see [the full user documentation](Users_guide/index.md).

mkdocs.yml

@@ -0,0 +1,12 @@
+---
+
+# Configuration options: https://www.mkdocs.org/user-guide/configuration/
+
+site_name: "Anthill"
+site_description: "A Kubernetes/OpenShift operator to manage Gluster clusters"
+repo_url: "https://github.com/gluster/anthill/"
+edit_uri: "blob/master/docs/"
+# readthedocs.org supports only mkdocs or readthedocs themes
+theme: "mkdocs"
+# Broken documentation links break the build
+strict: true