Update Index file documentation

Change-Id: Ifaadcc99d79693dd5a72066e3507b7ee73eae79f
This commit is contained in:
Anusha Ramineni 2017-06-30 09:06:23 +05:30 committed by Eric Kao
parent e405a1ee79
commit 866e8a43ad
5 changed files with 58 additions and 224 deletions

View File

@ -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__))
ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
sys.path.insert(0, os.path.abspath('../..'))
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'
# 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()
copyright = u'2017, OpenStack Foundation'
# 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'
nitpicky = False
# primary_domain = 'py'
# 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 -------------------------------------------------

View File

@ -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

View File

@ -1,84 +1,31 @@
===============================
Congress Dashboard
===============================
=============================================
Welcome to Congress Dashboard Documentation!
=============================================
Horizon Plugin for Congress
Introduction
============
* Free software: Apache license
* Source: http://git.openstack.org/cgit/openstack/congress-dashboard
* Bugs: http://bugs.launchpad.net/congress
Congress Dashboard is an extension for OpenStack Dashboard that provides a UI
for Congress that allows user to easily write the policies and rules for
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
--------------------
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
=============
Contents
========
.. toctree::
:glob:
:maxdepth: 1
:maxdepth: 1
releases/*
Source Code Reference
=====================
.. toctree::
:glob:
:maxdepth: 1
sourcecode/autoindex
Introduction to Congress <https://docs.openstack.org/developer/congress/README.html#congress-introduction-and-installation>
readme
Contributing <contributing>
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

4
doc/source/readme.rst Normal file
View File

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

View File

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