Merge "Use doc8 for documentation generation"

doc/source/conf.py

@@ -48,10 +48,11 @@ sys.setrecursionlimit(4000)
 extensions = [
     'sphinx.ext.autodoc',
     'openstackdocstheme',
-    'metadata-docs-rhel7',
     'sphinxcontrib.rsvgconverter',
 ]
 
+#    'metadata-docs-rhel7',
+
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
 

doc/source/controls-rhel7.rst

@@ -2,7 +2,7 @@ Security hardening controls in detail (RHEL 7 STIG)
 ===================================================
 
 The ansible-hardening role follows the Red Hat Enteprise Linux 7
-`Security Technical Implementation Guide (STIG)`_. The guide has over 200
+Security Technical Implementation Guide (STIG). The guide has over 200
 controls that apply to various parts of a Linux system, and it is updated
 regularly by the Defense Information Systems Agency (DISA). DISA is part of the
 United States Department of Defense. The current version of the openstack-
@@ -52,16 +52,7 @@ Controls are divided into groups based on the following properties:
     itself. For example, all tasks tagged with ``auditd`` are found within
     ``tasks/rhel7stig/auditd.yml``.
 
-.. _Security Technical Implementation Guide (STIG): http://iase.disa.mil/stigs/os/unix-linux/Pages/red-hat.aspx
-
 Although the STIG is specific to Red Hat Enterprise Linux 7, it also applies to
 CentOS 7 systems. In addition, almost all of the controls are easily translated
 for Ubuntu 16.04, openSUSE Leap and SUSE Linux Enterprise 12. Any deviations
 during translation are noted within the documentation below.
-
-.. toctree::
-   :maxdepth: 2
-
-   rhel7/auto_controls-by-severity.rst
-   rhel7/auto_controls-by-status.rst
-   rhel7/auto_controls-all.rst

doc/source/rhel7/domains/accounts.rst

@@ -15,5 +15,3 @@ coordination.
 Deployers should consider an authentication solution that uses centralized
 authentication, such as LDAP, Active Directory, or Kerberos, for the best
 security posture.
-
-.. include:: auto_accounts.rst

doc/source/rhel7/domains/aide.rst

@@ -36,5 +36,3 @@ To avoid installing and initializing AIDE, set the following Ansible variable:
 .. code-block:: yaml
 
     security_rhel7_enable_aide: false
-
-.. include:: auto_aide.rst

doc/source/rhel7/domains/auditd.rst

@@ -44,5 +44,3 @@ Handling audit emergencies
     issues on production systems, ranging from a reduction in security to
     servers going offline unexpectedly. There is extensive documentation in the
     developer notes below for each STIG requirement.
-
-.. include:: auto_auditd.rst

doc/source/rhel7/domains/auth.rst

@@ -11,5 +11,3 @@ Most of the STIG requirements for authentication are already included in Linux
 distributions by default or are easily applied without disruptions. Deployers
 should review the documentation below and test all changes on a non-production
 system first.
-
-.. include:: auto_auth.rst

doc/source/rhel7/domains/file_perms.rst

@@ -13,5 +13,3 @@ production systems if the permissions were adjusted to meet the needs of a
 particular application. These configurations are applied on an opt-in basis.
 Deployers must verify that these changes work well with their systems before
 applying the changes.
-
-.. include:: auto_file_perms.rst

doc/source/rhel7/domains/graphical.rst

@@ -13,5 +13,3 @@ authentication for new sessions and enforcing re-authentication after idle
 periods.
 
 These controls will be skipped on systems without a graphical login interface.
-
-.. include:: auto_graphical.rst

doc/source/rhel7/domains/kernel.rst

@@ -14,5 +14,3 @@ these changes.
 
 One deviation appears in this section for IP forwarding. Review the
 documentation for ``V-72309`` below for more details.
-
-.. include:: auto_kernel.rst

doc/source/rhel7/domains/lsm.rst

@@ -12,5 +12,3 @@ Overview
 The STIG requires that SELinux is in enforcing mode to provide additional
 security against attacks. The security role will enable SELinux on CentOS
 systems and enable AppArmor on Ubuntu and Debian systems.
-
-.. include:: auto_lsm.rst

doc/source/rhel7/domains/misc.rst

@@ -23,5 +23,3 @@ running on each host. That could be changed by using the
 ``security_allowed_ntp_subnets`` parameter.
 
 .. _RFC1918: https://en.wikipedia.org/wiki/Private_network#Private_IPv4_address_spaces
-
-.. include:: auto_misc.rst

doc/source/rhel7/domains/packages.rst

@@ -4,10 +4,3 @@ packages - Package managers
 Package managers provide a convenient, secure method for installing and
 upgrading applications on a system. They must be configured properly to ensure
 that software is carefully verified before it is installed.
-
-Overview
---------
-
-Lorem ipsum
-
-.. include:: auto_packages.rst

doc/source/rhel7/domains/sshd.rst

@@ -19,5 +19,3 @@ Deviation for PermitRootLogin
 
   However, this can cause problems in some existing environments and the
   default for the role is to set it to ``yes`` (direct root logins allowed).
-
-.. include:: auto_sshd.rst

tox.ini

@@ -1,10 +1,9 @@
 [tox]
-minversion = 3.1
+minversion = 3.18.0
 skipsdist = True
 envlist = docs,linters,functional
 ignore_basepython_conflict = True
 
-
 [testenv]
 basepython = python3
 usedevelop = False
@@ -29,73 +28,60 @@ setenv =
     VIRTUAL_ENV={envdir}
     WORKING_DIR={toxinidir}
 
-
 [testenv:docs]
 deps =
-  -c{env:TOX_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+  -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
   -r{toxinidir}/doc/requirements.txt
-  -r{toxinidir}/test-requirements.txt
 commands =
     bash -c "rm -rf doc/build"
-    # NOTE(mhayden): doc8 really dislikes the automated docs. This should be
-    # enabled again later.
-    #doc8 doc
-    sphinx-build -W -b html doc/source doc/build/html
+    doc8 doc
+    sphinx-build -W --keep-going -b html doc/source doc/build/html
 
 [testenv:pdf-docs]
 deps = {[testenv:docs]deps}
 allowlist_externals =
   make
 commands =
-  sphinx-build -W -b latex doc/source doc/build/pdf
+  sphinx-build -W --keep-going -b latex doc/source doc/build/pdf
   make -C doc/build/pdf
 
-
 [doc8]
 # Settings for doc8:
 extensions = .rst
-allow-long-titles=1
-
+ignore = D001
 
 [testenv:releasenotes]
 deps = {[testenv:docs]deps}
 commands =
-    sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
-
+    sphinx-build -a -E -W -d releasenotes/build/doctrees --keep-going -b html releasenotes/source releasenotes/build/html
 
 # environment used by the -infra templated docs job
 [testenv:venv]
 commands =
     {posargs}
 
-
 [testenv:pep8]
 commands =
     bash -c "{toxinidir}/tests/common/test-pep8.sh"
 
-
 [flake8]
 # Ignores the following rules due to how ansible modules work in general
 #     F403 'from ansible.module_utils.basic import *' used;
 #          unable to detect undefined names
 ignore=F403
 
-
 [testenv:bashate]
 commands =
     bash -c "{toxinidir}/tests/common/test-bashate.sh"
 
-
 [testenv:ansible-syntax]
 commands =
     bash -c "{toxinidir}/tests/common/test-ansible-syntax.sh"
 
-
 [testenv:ansible-lint]
 commands =
     bash -c "{toxinidir}/tests/common/test-ansible-lint.sh"
 
-
 [testenv:functional]
 setenv =
     {[testenv]setenv}