From 313a6d5b5801186bedb01c188f4de3c878332154 Mon Sep 17 00:00:00 2001 From: Samuel Cassiba Date: Fri, 20 Jul 2018 23:13:01 -0700 Subject: [PATCH] [Docs] Fix docs configuration Change-Id: I31d63da4fd43e6cf7790bedffd8a40a1d5103c36 --- .gitignore | 2 + doc/requirements.txt | 11 ++++- doc/source/_static/.gitkeep | 0 doc/source/conf.py | 72 ++++++++++++++++++++++---------- doc/source/contributor/index.rst | 4 +- doc/source/index.rst | 4 +- doc/source/install/index.rst | 4 +- setup.cfg | 9 ++-- 8 files changed, 72 insertions(+), 34 deletions(-) create mode 100644 doc/source/_static/.gitkeep diff --git a/.gitignore b/.gitignore index a36b18b..d2adfa1 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,5 @@ vms/ .chef/local-mode-cache/ .project .tox +doc/build +*.egg-info diff --git a/doc/requirements.txt b/doc/requirements.txt index 626130f..b3abbc3 100644 --- a/doc/requirements.txt +++ b/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 -pbr>=1.6 # Apache-2.0 +openstackdocstheme>=1.18.1 # Apache-2.0 +reno>=2.5.0 # Apache-2.0 +sphinxmark>=0.1.14 # Apache-2.0 +doc8>=0.6.0 # Apache-2.0 diff --git a/doc/source/_static/.gitkeep b/doc/source/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/conf.py b/doc/source/conf.py index f6a19fa..fa51281 100644 --- a/doc/source/conf.py +++ b/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. -modindex_common_prefix = ['chef-openstack-guide.'] +# If true, `todo` and `todoList` produce output, else they produce nothing. +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', - u'OpenStack Contributors', 'manual'), + (master_doc, target_name + '.tex', + 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', - [author], 1) + (master_doc, target_name, + 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', - author, 'ChefOpenStackGuide', 'One line description of project.', - 'Miscellaneous'), + (master_doc, target_name, + title, author, bug_project, + 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 diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 2d336e8..22d868a 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -1,5 +1,5 @@ -Chef OpenStack Contributor Guide -================================ +Contributor Guide +================= .. toctree:: :maxdepth: 2 diff --git a/doc/source/index.rst b/doc/source/index.rst index 20f8aa6..5ab42d0 100644 --- a/doc/source/index.rst +++ b/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. diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 30ad87d..5460109 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -1,5 +1,5 @@ -Chef Openstack Install Guide -============================ +Install Guide +============= .. toctree:: :maxdepth: 2 diff --git a/setup.cfg b/setup.cfg index 0e9d7a7..03bac8e 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,13 +1,14 @@ [metadata] -name = chef-openstack-guide -summary = Chef OpenStack Guide +name = chef-openstack +summary = Chef cookbooks for deploying OpenStack description-file = README.md author = OpenStack -author-email = openstack@lists.openstack.org -home-page = http://www.openstack.org/ +author-email = openstack-dev@lists.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