Update Index file documentation

Change-Id: Ifaadcc99d79693dd5a72066e3507b7ee73eae79f

doc/source/conf.py

@@ -22,137 +22,11 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from __future__ import print_function
-
 import os
 import sys
 
-BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.abspath('../..'))
-ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
 
-sys.path.insert(0, ROOT)
-
-# This is required for ReadTheDocs.org, but isn't a bad idea anyway.
-os.environ.setdefault('DJANGO_SETTINGS_MODULE',
-                      'congress_dashboard.test.settings')
-
-from congress_dashboard \
-    import version as ui_ver
-
-
-def write_autodoc_index():
-
-    def find_autodoc_modules(module_name, sourcedir):
-        """returns a list of modules in the SOURCE directory."""
-        modlist = []
-        os.chdir(os.path.join(sourcedir, module_name))
-        print("SEARCHING %s" % sourcedir)
-        for root, dirs, files in os.walk("."):
-            for filename in files:
-                if filename == 'tests.py':
-                    continue
-                if filename.endswith(".py"):
-                    # remove the pieces of the root
-                    elements = root.split(os.path.sep)
-                    # replace the leading "." with the module name
-                    elements[0] = module_name
-                    # and get the base module name
-                    base, extension = os.path.splitext(filename)
-                    if not (base == "__init__"):
-                        elements.append(base)
-                    result = ".".join(elements)
-                    # print result
-                    modlist.append(result)
-        return modlist
-
-    RSTDIR = os.path.abspath(os.path.join(BASE_DIR, "sourcecode"))
-    SRCS = [('congress_dashboard', ROOT), ]
-
-    EXCLUDED_MODULES = ()
-    CURRENT_SOURCES = {}
-
-    if not(os.path.exists(RSTDIR)):
-        os.mkdir(RSTDIR)
-    CURRENT_SOURCES[RSTDIR] = ['autoindex.rst']
-
-    INDEXOUT = open(os.path.join(RSTDIR, "autoindex.rst"), "w")
-    INDEXOUT.write("""
-=================
-Source Code Index
-=================
-
-.. contents::
-   :depth: 1
-   :local:
-
-""")
-
-    for modulename, path in SRCS:
-        sys.stdout.write("Generating source documentation for %s\n" %
-                         modulename)
-        INDEXOUT.write("\n%s\n" % modulename.capitalize())
-        INDEXOUT.write("%s\n" % ("=" * len(modulename),))
-        INDEXOUT.write(".. toctree::\n")
-        INDEXOUT.write("   :maxdepth: 1\n")
-        INDEXOUT.write("\n")
-
-        MOD_DIR = os.path.join(RSTDIR, modulename)
-        CURRENT_SOURCES[MOD_DIR] = []
-        if not(os.path.exists(MOD_DIR)):
-            os.mkdir(MOD_DIR)
-        for module in find_autodoc_modules(modulename, path):
-            if any([module.startswith(exclude) for exclude
-                   in EXCLUDED_MODULES]):
-                print("Excluded module %s." % module)
-                continue
-            mod_path = os.path.join(path, *module.split("."))
-            generated_file = os.path.join(MOD_DIR, "%s.rst" % module)
-
-            INDEXOUT.write("   %s/%s\n" % (modulename, module))
-
-            # Find the __init__.py module if this is a directory
-            if os.path.isdir(mod_path):
-                source_file = ".".join((os.path.join(mod_path, "__init__"),
-                                        "py",))
-            else:
-                source_file = ".".join((os.path.join(mod_path), "py"))
-
-            CURRENT_SOURCES[MOD_DIR].append("%s.rst" % module)
-            # Only generate a new file if the source has changed or we don't
-            # have a doc file to begin with.
-            if not os.access(generated_file, os.F_OK) or (
-                    os.stat(generated_file).st_mtime <
-                    os.stat(source_file).st_mtime):
-                print("Module %s updated, generating new documentation."
-                      % module)
-                FILEOUT = open(generated_file, "w")
-                header = "The :mod:`%s` Module" % module
-                FILEOUT.write("%s\n" % ("=" * len(header),))
-                FILEOUT.write("%s\n" % header)
-                FILEOUT.write("%s\n" % ("=" * len(header),))
-                FILEOUT.write(".. automodule:: %s\n" % module)
-                FILEOUT.write("  :members:\n")
-                FILEOUT.write("  :undoc-members:\n")
-                FILEOUT.write("  :show-inheritance:\n")
-                FILEOUT.write("  :noindex:\n")
-                FILEOUT.close()
-
-    INDEXOUT.close()
-
-    # Delete auto-generated .rst files for sources which no longer exist
-    for directory, subdirs, files in list(os.walk(RSTDIR)):
-        for old_file in files:
-            if old_file not in CURRENT_SOURCES.get(directory, []):
-                print("Removing outdated file for %s" % old_file)
-                os.remove(os.path.join(directory, old_file))
-
-
-write_autodoc_index()
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-# sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration ----------------------------------------------------
 
@@ -163,15 +37,9 @@ write_autodoc_index()
 # They can be extensions coming with Sphinx (named 'sphinx.ext.*')
 # or your custom ones.
 extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.todo',
-              'sphinx.ext.coverage',
-              'sphinx.ext.viewcode',
               'openstackdocstheme',
               ]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
 # The suffix of source filenames.
 source_suffix = '.rst'
 
@@ -183,16 +51,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Congress Dashboard'
-copyright = u'2016, OpenStack Foundation'
+copyright = u'2017, OpenStack Foundation'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = ui_ver.version_info.version_string()
-# The full version, including alpha/beta/rc tags.
-release = ui_ver.version_info.release_string()
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -206,18 +65,18 @@ release = ui_ver.version_info.release_string()
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['**/#*', '**~', '**/#*#']
+# exclude_patterns = ['**/#*', '**~', '**/#*#']
 
 # The reST default role (used for this markup: `text`)
 # to use for all documents.
 # default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-# add_function_parentheses = True
+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
+add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
@@ -229,8 +88,8 @@ pygments_style = 'sphinx'
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
 
-primary_domain = 'py'
+# primary_domain = 'py'
-nitpicky = False
+# nitpicky = False
 
 
 # -- Options for HTML output --------------------------------------------------
@@ -270,7 +129,7 @@ html_theme_options = {
 # 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']
+# html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -315,7 +174,7 @@ html_last_updated_fmt = '%Y-%m-%d %H:%M'
 # html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Horizondoc'
+# htmlhelp_basename = 'Horizondoc'
 
 
 # -- Options for LaTeX output -------------------------------------------------

doc/source/contributing.rst

@@ -0,0 +1,20 @@
+.. _contributing:
+
+=======================
+Contribution Guide
+=======================
+
+.. include:: ../../CONTRIBUTING.rst
+
+Project Hosting Details
+-------------------------
+
+Bug tracker
+    https://launchpad.net/congress
+
+Code Hosting
+    https://git.openstack.org/cgit/openstack/congress-dashboard
+
+Code Review
+    https://review.openstack.org/#/q/status:open+project:openstack/congress-dashboard,n,z
+

doc/source/index.rst

@@ -1,84 +1,31 @@
-===============================
+=============================================
-Congress Dashboard
+Welcome to Congress Dashboard Documentation!
-===============================
+=============================================
 
-Horizon Plugin for Congress
+Introduction
+============
 
-* Free software: Apache license
+Congress Dashboard is an extension for OpenStack Dashboard that provides a UI
-* Source: http://git.openstack.org/cgit/openstack/congress-dashboard
+for Congress that allows user to easily write the policies and rules for
-* Bugs: http://bugs.launchpad.net/congress
+governance of cloud.
 
-Features
+For more information on Congress, see `the congress documentation`_.
---------
 
-* TODO
+.. _the congress documentation: http://docs.openstack.org/developer/congress/
 
-Enabling in DevStack
+Contents
---------------------
+========
-
-Add this repo as an external repository into your ``local.conf`` file::
-
-    [[local|localrc]]
-    enable_plugin congress-dashboard https://github.com/openstack/congress-dashboard
-
-Manual Installation
--------------------
-
-Begin by cloning the Horizon and Congress Dashboard repositories::
-
-    git clone https://github.com/openstack/horizon
-    git clone https://github.com/openstack/congress-dashboard
-
-Create a virtual environment and install Horizon dependencies::
-
-    cd horizon
-    python tools/install_venv.py
-
-Set up your ``local_settings.py`` file::
-
-    cp openstack_dashboard/local/local_settings.py.example openstack_dashboard/local/local_settings.py
-
-Open up the copied ``local_settings.py`` file in your preferred text
-editor. You will want to customize several settings:
-
--  ``OPENSTACK_HOST`` should be configured with the hostname of your
-   OpenStack server. Verify that the ``OPENSTACK_KEYSTONE_URL`` and
-   ``OPENSTACK_KEYSTONE_DEFAULT_ROLE`` settings are correct for your
-   environment. (They should be correct unless you modified your
-   OpenStack server to change them.)
-
-Install Congress Dashboard with all dependencies in your virtual environment::
-
-    tools/with_venv.sh pip install -e ../congress-dashboard/
-
-And enable it in Horizon::
-
-    ln -s ../congress-dashboard/congress_dashboard/enabled/_90_project_cafe_panelgroup.py openstack_dashboard/local/enabled
-    ln -s ../congress-dashboard/congress_dashboard/enabled/_91_project_cafe_drinks_panel.py openstack_dashboard/local/enabled
-
-To run horizon with the newly enabled Congress Dashboard plugin run::
-
-    ./run_tests.sh --runserver 0.0.0.0:8080
-
-to have the application start on port 8080 and the horizon dashboard will be
-available in your browser at http://localhost:8080/
-
-Release Notes
-=============
 
 .. toctree::
-  :glob:
    :maxdepth: 1
 
-  releases/*
+   Introduction to Congress <https://docs.openstack.org/developer/congress/README.html#congress-introduction-and-installation>
-
+   readme 
-Source Code Reference
+   Contributing <contributing>
-=====================
-
-.. toctree::
-  :glob:
-  :maxdepth: 1
-
-  sourcecode/autoindex
 
+Indices and tables
+==================
 
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/source/readme.rst

@@ -0,0 +1,4 @@
+==============================
+Installing Congress Dashboard
+==============================
+.. include:: ../../README.rst

setup.cfg

@@ -22,6 +22,10 @@ classifier =
 packages =
     congress_dashboard
 
+[pbr]
+autodoc_index_modules = True
+warnerrors = True
+
 [build_sphinx]
 all_files = 1
 build-dir = doc/build