[Docs] Fix docs configuration

Change-Id: I31d63da4fd43e6cf7790bedffd8a40a1d5103c36

.gitignore

@@ -15,3 +15,5 @@ vms/
 .chef/local-mode-cache/
 .project
 .tox
+doc/build
+*.egg-info

doc/requirements.txt

@@ -1,3 +1,10 @@
+# The order of packages is significant, because pip processes them in the order
+# of appearance. Changing the order has an impact on the overall integration
+# process, which may cause wedges in the gate later.
+
+# this is required for the docs build jobs
 sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
-openstackdocstheme>=1.18.0 # Apache-2.0
+openstackdocstheme>=1.18.1 # Apache-2.0
-pbr>=1.6 # Apache-2.0
+reno>=2.5.0 # Apache-2.0
+sphinxmark>=0.1.14 # Apache-2.0
+doc8>=0.6.0 # Apache-2.0

doc/source/conf.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
 # Configuration file for the Sphinx documentation builder.
@@ -16,20 +17,18 @@ import sys
 import openstackdocstheme
 
 # -- Chef OpenStack configuration --------------------------------------------
+target_name = 'chef-openstack-docs'
+description = 'Chef OpenStack uses Chef to deploy OpenStack environments.'
 previous_series_name = 'pike'
 current_series_name = 'queens'
 
 # -- Project information -----------------------------------------------------
 
 title = u'Chef OpenStack Documentation'
-copyright = u'2018, Chef OpenStack Contributors'
+category = 'Miscellaneous'
+copyright = u'2014-2018, Chef OpenStack Contributors'
 author = u'Chef OpenStack Contributors'
 
-# The short X.Y version
-version = u''
-# The full version, including alpha/beta/rc tags
-release = u''
-
 current_series = openstackdocstheme.ext._get_series_name()
 
 if current_series == "latest":
@@ -70,8 +69,9 @@ rst_epilog = """
 extensions = [
     'openstackdocstheme',
     'sphinx.ext.autodoc',
-    'sphinx.ext.todo',
+    'sphinx.ext.extlinks',
     'sphinx.ext.viewcode',
+    'sphinxmark'
 ]
 
 todo_include_docs = True
@@ -85,6 +85,11 @@ source_suffix = '.rst'
 # The master toctree document.
 master_doc = 'index'
 
+# openstackdocstheme options
+repository_name = 'openstack/openstack-chef-repo'
+bug_project = 'openstack-chef'
+bug_tag = ''
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -100,8 +105,8 @@ exclude_patterns = ['_build']
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# A list of ignored prefixes for mod_index sorting.
+# If true, `todo` and `todoList` produce output, else they produce nothing.
-modindex_common_prefix = ['chef-openstack-guide.']
+todo_include_todos = False
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -110,6 +115,20 @@ modindex_common_prefix = ['chef-openstack-guide.']
 #
 html_theme = 'openstackdocs'
 
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+# html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
+
 # 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.
@@ -127,8 +146,10 @@ html_theme = 'openstackdocs'
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'ChefOpenStackGuidedoc'
+htmlhelp_basename = 'chef-openstack-docs'
 
+# If true, publish source files
+html_copy_source = False
 
 # -- Options for LaTeX output ------------------------------------------------
 
@@ -154,18 +175,17 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ChefOpenStackGuide.tex', u'Chef OpenStack Guide Documentation',
+  (master_doc, target_name + '.tex',
-     u'OpenStack Contributors', 'manual'),
+   title, author, 'manual'),
 ]
 
-
 # -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'chefopenstackguide', u'Chef OpenStack Guide Documentation',
+    (master_doc, target_name,
-     [author], 1)
+     title, [author], 1)
 ]
 
 
@@ -175,15 +195,23 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'ChefOpenStackGuide', u'Chef OpenStack Guide Documentation',
+    (master_doc, target_name,
-     author, 'ChefOpenStackGuide', 'One line description of project.',
+     title, author, bug_project,
-     'Miscellaneous'),
+     description, category),
 ]
 
+# -- Options for PDF output --------------------------------------------------
 
-# -- Extension configuration -------------------------------------------------
+pdf_documents = [
+    (master_doc, target_name,
+     title, author)
+]
 
-# -- Options for todo extension ----------------------------------------------
+# -- Options for sphinxmark -----------------------------------------------
+sphinxmark_enable = True
+sphinxmark_div = 'docs-body'
+sphinxmark_image = 'text'
+sphinxmark_text = watermark
+sphinxmark_text_color = (128, 128, 128)
+sphinxmark_text_size = 70
 
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True

doc/source/contributor/index.rst

@@ -1,5 +1,5 @@
-Chef OpenStack Contributor Guide
+Contributor Guide
-================================
+=================
 
 .. toctree::
    :maxdepth: 2

doc/source/index.rst

@@ -1,5 +1,5 @@
-Welcome to the Chef OpenStack Guide!
+Chef OpenStack Documentation
-=====================================
+============================
 
 The Chef cookbooks for OpenStack automate the building, operation and
 consumption of OpenStack cloud deployments.

doc/source/install/index.rst

@@ -1,5 +1,5 @@
-Chef Openstack Install Guide
+Install Guide
-============================
+=============
 
 .. toctree::
    :maxdepth: 2

setup.cfg

@@ -1,13 +1,14 @@
 [metadata]
-name = chef-openstack-guide
+name = chef-openstack
-summary = Chef OpenStack Guide
+summary = Chef cookbooks for deploying OpenStack
 description-file =
     README.md
 author = OpenStack
-author-email = openstack@lists.openstack.org
+author-email = openstack-dev@lists.openstack.org
-home-page = http://www.openstack.org/
+home-page = https://docs.openstack.org/chef-openstack/latest/
 classifier =
     Intended Audience :: Developers
+    Intended Audience :: System Administrators
     License :: OSI Approved :: Apache Software License
     Operating System :: POSIX :: Linux