Merge pull request #35 from JohnStrunk/theme-fix

Fix theme to match readthedocs

docs/Developers/Editing_the_documentation.md

@@ -1,5 +1,3 @@
-# Editing the documentation
-
 The documentation resides in the main Anthill repo, under the `/docs`
 directory as a set of markdown files.
 
@@ -10,7 +8,7 @@ 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
+# Building locally
 
 The mkdocs tool can be installed via pip:
 
@@ -31,18 +29,20 @@ 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
+# 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
+- The outline in the sidebar follows the structure of the `/docs` directory
+  tree.
+- The outline is sorted alphabetically by the name of the file.
+- File names become the entries in the sidebar. Case is preserved, and
   underscores become spaces.
-- Each page has its outline displayed on the left.
+- Each page has its outline displayed when selected.
+- Don't repeat the document "title" aka file name at the top of the document
+  (as seems to be common practice), otherwise there will be redundant headers
+  in the sidebar.
 - Links within the documentation should be relative links to the `*.md` source
   file. The documentation builder will make it point to the correct place.
 

docs/Developers/Testing_and_validation.md

@@ -1,8 +1,6 @@
-# Testing and validation
-
 This page provides an overview of the project's testing infrastructure.
 
-## Git pre-commit hook
+# 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
@@ -37,7 +35,7 @@ cd .git/hooks
 ln -s ../../scripts/pre-commit.sh pre-commit
 ```
 
-## CI infrastructure
+# CI infrastructure
 
 The project makes use of Travis CI for linting (and soon, unit testing).
 

mkdocs.yml

@@ -6,7 +6,7 @@ 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"
+# readthedocs.org supports only readthedocs theme
+theme: "readthedocs"
 # Broken documentation links break the build
 strict: true