From 42f3e2961a2c6f496815e7d940a592543aadf6fd Mon Sep 17 00:00:00 2001 From: Tim Kelsey Date: Fri, 24 Jul 2015 12:53:29 +0100 Subject: [PATCH] Adding documentation framework This adds documentation framework for Bandit. To build the new documentation you can use the new tox target: tox -e docs This will spit out various formatted output into the docs/build folder. Change-Id: I3497e26052021900ad55ecdd2517198b22e82f0e Partial-Bug: 1474796 --- .gitignore | 1 + docs/{ => old}/exec.md | 0 docs/{ => old}/jinja2.md | 0 docs/{ => old}/partial_paths.md | 0 docs/{ => old}/ssl_tls.md | 0 docs/{ => old}/temp.md | 0 docs/{ => old}/xml.md | 0 docs/{ => old}/yaml.md | 0 docs/source/conf.py | 76 +++++++++++++++++++++++++++++++++ docs/source/index.rst | 2 + setup.cfg | 5 +++ test-requirements.txt | 3 ++ tox.ini | 4 ++ 13 files changed, 91 insertions(+) rename docs/{ => old}/exec.md (100%) rename docs/{ => old}/jinja2.md (100%) rename docs/{ => old}/partial_paths.md (100%) rename docs/{ => old}/ssl_tls.md (100%) rename docs/{ => old}/temp.md (100%) rename docs/{ => old}/xml.md (100%) rename docs/{ => old}/yaml.md (100%) create mode 100755 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/.gitignore b/.gitignore index 36a192df..ca370da2 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ venv* build/* cover/* .cover +docs/build/* diff --git a/docs/exec.md b/docs/old/exec.md similarity index 100% rename from docs/exec.md rename to docs/old/exec.md diff --git a/docs/jinja2.md b/docs/old/jinja2.md similarity index 100% rename from docs/jinja2.md rename to docs/old/jinja2.md diff --git a/docs/partial_paths.md b/docs/old/partial_paths.md similarity index 100% rename from docs/partial_paths.md rename to docs/old/partial_paths.md diff --git a/docs/ssl_tls.md b/docs/old/ssl_tls.md similarity index 100% rename from docs/ssl_tls.md rename to docs/old/ssl_tls.md diff --git a/docs/temp.md b/docs/old/temp.md similarity index 100% rename from docs/temp.md rename to docs/old/temp.md diff --git a/docs/xml.md b/docs/old/xml.md similarity index 100% rename from docs/xml.md rename to docs/old/xml.md diff --git a/docs/yaml.md b/docs/old/yaml.md similarity index 100% rename from docs/yaml.md rename to docs/old/yaml.md diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100755 index 00000000..bbdd143a --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,76 @@ +# -*- coding: utf-8 -*- +# 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. + +import os +import sys + +sys.path.insert(0, os.path.abspath('../..')) +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + # 'sphinx.ext.intersphinx', + 'oslosphinx' +] + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Bandit' +copyright = u'2015, OpenStack Foundation' + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +# html_theme = '_theme' +# html_static_path = ['static'] +html_theme_options = {} + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', + '%s.tex' % project, + u'%s Documentation' % project, + u'OpenStack Foundation', 'manual'), +] + +# Example configuration for intersphinx: refer to the Python standard library. +# intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..e3e6880e --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,2 @@ +Bandit Documentation +==================== diff --git a/setup.cfg b/setup.cfg index be904f1e..3263ec4a 100644 --- a/setup.cfg +++ b/setup.cfg @@ -119,3 +119,8 @@ package_data = data_files = bandit = share/bandit/wordlist/ = wordlist/default-passwords + +[build_sphinx] +all_files = 1 +build-dir = docs/build +source-dir = docs/source diff --git a/test-requirements.txt b/test-requirements.txt index e311cd07..1e7002cd 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -7,3 +7,6 @@ python-subunit>=0.0.18 testrepository>=0.0.18 testscenarios>=0.4 testtools>=0.9.36,!=1.2.0 + +sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3 +oslosphinx>=2.5.0 # Apache-2.0 diff --git a/tox.ini b/tox.ini index cacae83a..185733d3 100644 --- a/tox.ini +++ b/tox.ini @@ -26,6 +26,10 @@ deps = PyYAML>=3.1.0 requests>=2.7.0 commands = python tools/openstack_coverage.py +[testenv:docs] +commands= + python setup.py build_sphinx + [flake8] # E123, E125 skipped as they are invalid PEP-8. # H303 no wild card imports