Enable warning-is-error in doc build

- Fix docstring warnings
- pbr warnerrors is no longer needed.
- pbr audodoc temporarily disabled

Co-authored-By: Nguyen Van Trung <trungnv@vn.fujitsu.com>
Change-Id: I37d5d78fc7895bd112a8555840c6c3b3eb294ad3

README.rst

@@ -7,7 +7,6 @@ Team and repository tags
 
 .. Change things from this point on
 
-.. include:: aliases.rst
 
 .. _readme:
 

doc/source/aliases.rst

@@ -1,3 +0,0 @@
-
-.. |ad| replace:: ActiveDirectory
-

doc/source/api.rst

@@ -1,4 +1,3 @@
-.. include:: aliases.rst
 
 .. _api:
 
@@ -35,6 +34,7 @@ and *action*.  A policy has the following fields:
         b) action,
         c) database,
         d) materialized
+
         The default is *nonrecursive* and unless you are writing action
         descriptions for use with ``simulate`` you should always use the
         default.

doc/source/architecture.rst

@@ -1,4 +1,3 @@
-.. include:: aliases.rst
 
 .. _concepts:
 
@@ -24,7 +23,7 @@ other cloud services that act as sources of information about the cloud::
 
 A service is anything that manages cloud state.  For example,
 OpenStack components like Nova, Neutron, Cinder, Swift, Heat, and
-Keystone are all services.  Software like |ad|, inventory management
+Keystone are all services.  Software like ActiveDirectory, inventory management
 systems, anti-virus scanners, intrusion detection systems, and
 relational databases are also services.
 

doc/source/cloudservices.rst

@@ -1,4 +1,3 @@
-.. include:: aliases.rst
 
 .. _cloudservices:
 

doc/source/codeoverview.rst

@@ -1,5 +1,4 @@
 
-.. include:: aliases.rst
 
 .. _codeoverview:
 

doc/source/conf.py

@@ -15,6 +15,8 @@ import os
 import sys
 
 sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath('./'))
 # -- General configuration ----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be

doc/source/deployment.rst

@@ -1,4 +1,3 @@
-.. include:: aliases.rst
 
 .. _deployment:
 
@@ -98,5 +97,12 @@ are specified in the [DEFAULT] section of the configuration file.
     [DEFAULT]
     transport_url = rabbit://<rabbit-userid>:<rabbit-password>@<rabbit-host-address>:<port>
 
-.. include:: ha-overview.rst
-.. include:: ha-deployment.rst
+=============
+HA Deployment
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   ha-overview
+   ha-deployment

doc/source/enforcement.rst

@@ -1,4 +1,3 @@
-.. include:: aliases.rst
 
 .. _enforcement:
 

doc/source/ha-deployment.rst

@@ -1,14 +1,12 @@
-.. include:: aliases.rst
 
 .. _ha_deployment:
 
-
--------------
+#############
 HA Deployment
--------------
+#############
 
 Overview
-==================
+========
 
 This section shows how to deploy Congress with High Availability (HA). For an
 architectural overview, please see the :ref:`HA Overview <ha_overview>`.
@@ -26,7 +24,7 @@ The following sections describe each step in more detail.
 
 
 Shared Services
-==================
+===============
 
 All the Congress nodes share a database backend. To setup a database backend
 for Congress, please follow the database portion of
@@ -48,7 +46,7 @@ __ http://docs.openstack.org/ha-guide/shared-messaging.html
 
 
 Hosts Preparation
-==================
+=================
 
 Congress should be installed on each host expected to run a Congress node.
 Please follow the directions in `separate install instructions`__ to install
@@ -88,7 +86,7 @@ For example:
 
 
 Datasource Drivers Node
-========================
+=======================
 
 In this step, we deploy a single datasource-drivers node in warm-standby style.
 
@@ -154,7 +152,7 @@ The RA has following configurable parameters.
 
 
 Policy Engine Nodes
-=====================
+===================
 
 In this step, we deploy N (at least 2) policy-engine nodes, each with an
 associated API server. This step should be done only after the
@@ -173,7 +171,7 @@ congress configuration file.
 
 
 Load-balancer
-==============
+=============
 
 A load-balancer should be used to distribute incoming API requests to the N
 policy-engine (and API service) nodes deployed in step 3.

doc/source/ha-overview.rst

@@ -1,11 +1,9 @@
 
-.. include:: aliases.rst
-
 .. _ha_overview:
 
------------
+###########
 HA Overview
------------
+###########
 Some applications require Congress to be highly available. Some
 applications require a Congress Policy Engine (PE) to handle a high volume of
 queries. This guide describes Congress support for High Availability (HA)
@@ -16,6 +14,7 @@ install and configure OpenStack for High Availability.
 
 __ http://docs.openstack.org/ha-guide/index.html
 
+
 HA Types
 ========
 
@@ -167,4 +166,4 @@ Cautions and Limitations
   configuring the load balancer to make each user sticky to a particular PE
   instance. But if a user reaches a different PE instance (say because of load
   balancer configuration or because the original instance went down), the end
-  user reaches a different instance and may experience out-of-sync artifacts.
+  user reaches a different instance and may experience out-of-sync artifacts.

doc/source/inactive/aliases.rst

@@ -1 +0,0 @@
-../aliases.rst

doc/source/inactive/intro.rst.inactive

@@ -1,6 +1,4 @@
 
-.. include:: aliases.rst
-
 .. _introduction:
 
 Introduction

doc/source/inactive/other_enforcement.rst.inactive

@@ -1,3 +1,4 @@
+
 .. _other-enforcement:
 
 Other Enforcement Techniques

doc/source/inactive/policy_engine.rst.inactive

@@ -1,6 +1,5 @@
-.. include:: aliases.rst
 
-.. _policy-engine:
+.. _policy_engine:
 
 Policy Engine
 --------------

doc/source/inactive/related.rst.inactive

@@ -1,6 +1,4 @@
 
-.. include:: aliases.rst
-
 .. _relatedwork:
 
 ============
@@ -9,10 +7,10 @@ Related Work
 This page describes comparisons of Congress to other well-known systems.
 
 
-1. |ad|
-=======
+1. ActiveDirectory
+==================
 
-In many ways Congress is similar to |ad| (AD).
+In many ways Congress is similar to ActiveDirectory (AD).
 
 * Both Congress and AD are cloud services whose main responsibility is policy.
 * Both Congress and AD are concerned with providing a single touchpoint for
@@ -22,7 +20,7 @@ In many ways Congress is similar to |ad| (AD).
   like groups that make it easy to express policies over large numbers of
   servers, networks, users, files, etc.
 
-Congress generalizes |ad| in several dimensions.
+Congress generalizes ActiveDirectory in several dimensions.
 
 * AD is primarily used for managing a collection of servers.  Congress is
   designed to manage any collection of cloud services.  Congress does not

doc/source/policy.rst

@@ -1,4 +1,3 @@
-.. include:: aliases.rst
 
 .. _policy:
 
@@ -68,7 +67,7 @@ Neutron tables), or the tables may come from different cloud services (e.g.
 some tables from Neutron, others from Nova).
 
 For example, if we have the following table schemas from Nova, Neutron, and
-|ad|, we could write a policy that says every network connected to a VM must
+ActiveDirectory, we could write a policy that says every network connected to a VM must
 either be public or owned by someone in the same group as the VM owner.::
 
   error(vm, network) :-
@@ -395,8 +394,8 @@ In previous releases, the *builtin:* prefix was unnecessary.  You could referenc
 builtin tables in their bare form, e.g. *lt(x,y)*.  As of Ocata, bare references
 to builtins are deprecated.
 
-**Bare builtin references are deprecated as of Ocata.  They will be removed
-  in the Q release.**
+**Bare builtin references are deprecated as of Ocata.They will be removed
+in the Q release.**
 
 Here is a list of the currently supported builtins.  A builtin that has
 N inputs means that the leftmost N columns are the inputs, and the

doc/source/release.rst

@@ -1,4 +1,3 @@
-.. include:: aliases.rst
 
 .. _release:
 

doc/source/troubleshooting.rst

@@ -1,4 +1,3 @@
-.. include:: aliases.rst
 
 .. _troubleshooting:
 

setup.cfg

@@ -29,13 +29,16 @@ packages =
 setup-hooks =
     pbr.hooks.setup_hook
 
-[pbr]
-autodoc_index_modules = True
-autodoc_exclude_modules =
-     congress.db.migration.alembic_migrations.*
-     congress_tempest_tests.*
-     thirdparty.*
-warnerrors = True
+# FIXME: fix the docstrings to comply with format. Re-enable this module
+# when warning-errors resolved.
+# [pbr]
+# autodoc_index_modules = True
+# autodoc_exclude_modules =
+#      congress.db.migration.alembic_migrations.*
+#      congress_tempest_tests.*
+#      thirdparty.*
+#      antlr3runtime.*
+# warnerrors = True
 
 [entry_points]
 oslo.config.opts =
@@ -53,9 +56,10 @@ tempest.test_plugins =
 
 
 [build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
 all_files = 1
+build-dir = doc/build
+source-dir = doc/source
+warning-is-error = 1
 
 [upload_sphinx]
 upload-dir = doc/build/html

tox.ini

@@ -8,6 +8,7 @@ usedevelop = True
 
 install_command = pip install -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt} -U {opts} {packages}
 whitelist_externals = find
+                      rm
 setenv =
    VIRTUAL_ENV={envdir}
    LANG=en_US.UTF-8
@@ -56,7 +57,8 @@ commands = {toxinidir}/tools/pip-install-single-req.sh requirements.txt oslo.con
 
 [testenv:docs]
 setenv = PYTHONHASHSEED=0
-commands = python setup.py build_sphinx
+commands = rm -rf doc/build doc/source/api
+           python setup.py build_sphinx
 
 [testenv:releasenotes]
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html