doc migration: openstackdocstheme completion

Finish the transition to the openstackdocs theme in accord
with the OpenStack manuals project migration spec [1].

Also remove the already broken autodoc build since
it generates warnings (which we treat as errors) with
the new theme setup.

[1] https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html

Partial-Bug: #1706181
Needed-By: Ieea33262101a1d2459492c1c8aaac5fe042279f6
Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454

Change-Id: Ifc80fc56648cef74c85464321d1850e8c68449a0

doc/ext/manila_autodoc.py

@@ -1,26 +0,0 @@
-#  Licensed under the Apache License, Version 2.0 (the "License"); you may
-#  not use this file except in compliance with the License. You may obtain
-#  a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-#  Unless required by applicable law or agreed to in writing, software
-#  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-#  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-#  License for the specific language governing permissions and limitations
-#  under the License.
-
-from __future__ import print_function
-
-import gettext
-import os
-
-gettext.install('manila')
-
-from manila import utils
-
-
-def setup(app):
-    print("**Autodocumenting from %s" % os.path.abspath(os.curdir))
-    rv = utils.execute('./doc/generate_autodoc_index.sh')
-    print(rv[0])

doc/find_autodoc_modules.sh

@@ -1,20 +0,0 @@
-#!/bin/bash
-
-MANILA_DIR='manila/' # include trailing slash
-DOCS_DIR='source'
-
-modules=''
-for x in `find ${MANILA_DIR} -name '*.py' | grep -v manila/tests`; do
-    if [ `basename ${x} .py` == "__init__" ] ; then
-        continue
-    fi
-    relative=manila.`echo ${x} | sed -e 's$^'${MANILA_DIR}'$$' -e 's/.py$//' -e 's$/$.$g'`
-    modules="${modules} ${relative}"
-done
-
-for mod in ${modules} ; do
-  if [ ! -f "${DOCS_DIR}/${mod}.rst" ];
-  then
-    echo ${mod}
-  fi
-done

doc/generate_autodoc_index.sh

@@ -1,46 +0,0 @@
-#!/bin/sh
-
-SOURCEDIR=doc/source/api
-
-if [ ! -d ${SOURCEDIR} ] ; then
-    mkdir -p ${SOURCEDIR}
-fi
-
-for x in `./find_autodoc_modules.sh`;
-do
-  echo "Generating ${SOURCEDIR}/${x}.rst"
-  echo "${SOURCEDIR}/${x}.rst" >> .autogenerated 
-  heading="The :mod:\`${x}\` Module"
-  # Figure out how long the heading is
-  # and make sure to emit that many '=' under
-  # it to avoid heading format errors
-  # in Sphinx.
-  heading_len=$(echo "$heading" | wc -c)
-  underline=$(head -c $heading_len < /dev/zero | tr '\0' '=')
-  ( cat <<EOF
-${heading}
-${underline}
-
-.. automodule:: ${x}
-  :members:
-  :undoc-members:
-  :show-inheritance:
-EOF
-) > ${SOURCEDIR}/${x}.rst
-
-done
-
-if [ ! -f ${SOURCEDIR}/autoindex.rst ] ; then
-
-    cat > ${SOURCEDIR}/autoindex.rst <<EOF 
-.. toctree::
-   :maxdepth: 1
-
-EOF
-    for f in `cat .autogenerated | sort` ; do
-        relative=`echo ${f} | sed -e 's$^'${SOURCEDIR}'/$$'`
-        echo "   ${relative}" >> ${SOURCEDIR}/autoindex.rst
-    done
-
-    echo ${SOURCEDIR}/autoindex.rst >> .autogenerated
-fi

doc/source/conf.py

@@ -53,14 +53,14 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.coverage',
               'sphinx.ext.ifconfig',
               'sphinx.ext.graphviz',
-              'oslosphinx',
+              'openstackdocstheme',
               ]
 
-# autodoc generation is a bit aggressive and a nuisance
+# openstackdocstheme options
-# when doing heavy text edit cycles. Execute "export SPHINX_DEBUG=1"
+repository_name = 'openstack/manila'
-# in your terminal to disable
+bug_project = 'manila'
-if not os.getenv('SPHINX_DEBUG'):
+bug_tag = 'docs'
-    extensions += ['ext.manila_autodoc']
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
 todo_include_todos = True
 
@@ -111,7 +111,6 @@ try:
 except Exception:
     warnings.warn('Cannot get gitsha.')
     gitsha = 'unknown'
-bug_tag = u'docs'
 # source tree
 pwd = os.getcwd()
 html_context = {
@@ -119,7 +118,7 @@ html_context = {
     "gitsha": gitsha,
     "bug_tag": bug_tag,
     "giturl": giturl,
-    "bug_project": "manila",
+    "bug_project": bug_project,
 }
 
 

doc/source/index.rst

@@ -43,7 +43,6 @@ Developer Docs
 
    devref/index
    man/index
-   api/autoindex
 
 Admin Docs
 ==========

install-guide/source/common/dhss-true-mode-using-shared-file-systems.rst

@@ -53,7 +53,7 @@ Create a share type
       <http://docs.openstack.org/admin-guide/shared-file-systems-share-types.html>_`.
 
 Create a manila server image
-------------------------
+----------------------------
 
    For evaluation of the Shared File Systems service, the image used by manila server must support
    network file system protocols such as NFS/CIFS. This guide creates a regular instance using the

releasenotes/source/conf.py

@@ -30,6 +30,8 @@
 
 # -- General configuration ------------------------------------------------
 
+import openstackdocstheme
+
 # If your documentation needs a minimal Sphinx version, state it here.
 # needs_sphinx = '1.0'
 
@@ -37,10 +39,16 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'oslosphinx',
     'reno.sphinxext',
+    'openstackdocstheme',
 ]
 
+# openstackdocstheme options
+repository_name = 'openstack/manila'
+bug_project = 'manila'
+bug_tag = 'release notes'
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -111,7 +119,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'openstackdocs'
 
 # 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
@@ -119,7 +127,7 @@ html_theme = 'default'
 # html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
+# html_theme_path = [openstackdocstheme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".

test-requirements.txt

@@ -12,7 +12,6 @@ fixtures>=3.0.0 # Apache-2.0/BSD
 mock>=2.0.0 # BSD
 iso8601>=0.1.11 # MIT
 oslotest>=1.10.0 # Apache-2.0
-oslosphinx>=4.7.0 # Apache-2.0
 openstackdocstheme>=1.16.0 # Apache-2.0
 
 # Do not remove 'PyMySQL' and 'psycopg2' dependencies. They are used