Merge ~powersj/cloud-init:docs/config-tox into cloud-init:master

[Joshua Powers]

doc: document doc, create makefile and tox target

* Create makefile and tox targets for documentation building and testing
to better replicate the live web docs using the same theme.
* Created docs.rst to explain how to build and contribute to documentation
with style guide and tips.
* doc/rtd/conf.py:
    * Add copyright to rtd config
    * Use Sphinx's RTD theme to replicate actual docs

[Server Team CI bot (server-team-bot)]

PASSED: Continuous integration, rev:3366a331a27d601159604fa1a4531167a45da623
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1102/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Unit & Style Tests
    SUCCESS: Ubuntu LTS: Build
    SUCCESS: Ubuntu LTS: Integration
    IN_PROGRESS: Declarative: Post Actions

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1102//rebuild

review: Approve (continuous-integration)

[Scott Moser (smoser)]

I don't personally feel the need to have 'make doc' at all, but its not a problem to have it.

In the commit message subject line you have 'create markefile'

[Joshua Powers (powersj)]

Thanks for the reviews.

Fixed the commit message and responded to comments below.

8a19f93... by Joshua Powers on 2019-09-04

fixes from review

[Server Team CI bot (server-team-bot)]

PASSED: Continuous integration, rev:8a19f935dd5bc037ef74e1820b73c1a38b421450
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1104/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Unit & Style Tests
    SUCCESS: Ubuntu LTS: Build
    SUCCESS: Ubuntu LTS: Integration
    IN_PROGRESS: Declarative: Post Actions

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1104//rebuild

review: Approve (continuous-integration)

7375eec... by Joshua Powers on 2019-09-06

clarify capitalization of cloud-init

also fix textwidth to be in line with doc

[Server Team CI bot (server-team-bot)]

PASSED: Continuous integration, rev:7375eec73e00b622f149527afd93a812dac7be68
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1105/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Unit & Style Tests
    SUCCESS: Ubuntu LTS: Build
    SUCCESS: Ubuntu LTS: Integration
    IN_PROGRESS: Declarative: Post Actions

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1105//rebuild

review: Approve (continuous-integration)

[Scott Moser (smoser)]

review: Approve

diff --git a/Makefile b/Makefile
index 4ace227..2c6d0c8 100644
--- a/Makefile
+++ b/Makefile
@@ -106,7 +106,9 @@ deb-src:
 		  echo sudo apt-get install devscripts; exit 1; }
 	$(PYVER) ./packages/bddeb -S -d
 
+doc:
+	tox -e doc
 
 .PHONY: test pyflakes pyflakes3 clean pep8 rpm srpm deb deb-src yaml
 .PHONY: check_version pip-test-requirements pip-requirements clean_pyc
-.PHONY: unittest unittest3 style-check
+.PHONY: unittest unittest3 style-check doc
diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py
index 4174477..9b27484 100644
--- a/doc/rtd/conf.py
+++ b/doc/rtd/conf.py
@@ -17,7 +17,8 @@ from cloudinit.config.schema import get_schema_doc
 # ]
 
 # General information about the project.
-project = 'Cloud-Init'
+project = 'cloud-init'
+copyright = '2019, Canonical Ltd.'
 
 # -- General configuration ----------------------------------------------------
 
@@ -59,15 +60,7 @@ show_authors = False
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-html_theme_options = {
-    "bodyfont": "Ubuntu, Arial, sans-serif",
-    "headfont": "Ubuntu, Arial, sans-serif"
-}
+html_theme = 'sphinx_rtd_theme'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
diff --git a/doc/rtd/index.rst b/doc/rtd/index.rst
index 20a99a3..c670b20 100644
--- a/doc/rtd/index.rst
+++ b/doc/rtd/index.rst
@@ -1,14 +1,5 @@
 .. _index:
 
-.. http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
-.. As suggested at link above for headings use:
-..   # with overline, for parts
-..   * with overline, for chapters
-..   =, for sections
-..   -, for subsections
-..   ^, for subsubsections
-..   “, for paragraphs
-
 #############
 Documentation
 #############
diff --git a/doc/rtd/topics/docs.rst b/doc/rtd/topics/docs.rst
new file mode 100644
index 0000000..1b15377
--- /dev/null
+++ b/doc/rtd/topics/docs.rst
@@ -0,0 +1,84 @@
+.. _docs:
+
+Docs
+****
+
+These docs are hosted on Read the Docs. The following will explain how to
+contribute to and build these docs locally.
+
+The documentation is primarily written in reStructuredText.
+
+
+Building
+========
+
+There is a makefile target to build the documentation for you:
+
+.. code-block:: shell-session
+
+    $ tox -e doc
+
+This will do two things:
+
+- Build the documentation using sphinx
+- Run doc8 against the documentation source code
+
+Once build the HTML files will be viewable in ``doc/rtd_html``. Use your
+web browser to open ``index.html`` to view and navigate the site.
+
+Style Guide
+===========
+
+Headings
+--------
+The headings used across the documentation use the following hierarchy:
+
+- ``*****``: used once atop of a new page
+- ``=====``: each sections on the page
+- ``-----``: subsections
+- ``^^^^^``: sub-subsections
+- ``"""""``: paragraphs
+
+The top level header ``######`` is reserved for the first page.
+
+If under and overline are used, their length must be identical. The length of
+the underline must be at least as long as the title itself
+
+Line Length
+-----------
+Please keep the line lengths to a maximum of **79** characters. This ensures
+that the pages and tables do not get too wide that side scrolling is required.
+
+Header
+------
+Adding a link at the top of the page allows for the page to be referenced by
+other pages. For example for the FAQ page this would be:
+
+.. code-block:: rst
+
+    .. _faq:
+
+Footer
+------
+The footer should include the textwidth
+
+.. code-block:: rst
+
+    .. vi: textwidth=79
+
+Vertical Whitespace
+-------------------
+One newline between each section helps ensure readability of the documentation
+source code.
+
+Common Words
+------------
+There are some common words that should follow specific usage:
+
+- ``cloud-init``: always lower case with a hyphen, unless starting a sentence
+  in which case only the 'C' is capitalized (e.g. ``Cloud-init``).
+- ``metadata``: one word
+- ``user data``: two words, not to be combined
+- ``vendor data``: like user data, it is two words
+
+.. vi: textwidth=79
diff --git a/tox.ini b/tox.ini
index 1f01eb7..f5baf32 100644
--- a/tox.ini
+++ b/tox.ini
@@ -53,8 +53,13 @@ exclude = .venv,.tox,dist,doc,*egg,.git,build,tools
 
 [testenv:doc]
 basepython = python3
-deps = sphinx
-commands = {envpython} -m sphinx {posargs:doc/rtd doc/rtd_html}
+deps =
+    doc8
+    sphinx
+    sphinx_rtd_theme
+commands =
+    {envpython} -m sphinx {posargs:doc/rtd doc/rtd_html}
+    doc8 doc/rtd
 
 [testenv:xenial]
 commands =