Update Index file documentation
Change-Id: Ifaadcc99d79693dd5a72066e3507b7ee73eae79f
This commit is contained in:
Anusha Ramineni
Eric Kao
parent
e405a1ee79
commit
866e8a43ad
@ -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 -------------------------------------------------
|
||||
|
||||
20
doc/source/contributing.rst
Normal file
20
doc/source/contributing.rst
Normal 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
|
||||
|
||||
@ -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
|
||||
|
||||
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
4
doc/source/readme.rst
Normal file
@ -0,0 +1,4 @@
|
||||
==============================
|
||||
Installing Congress Dashboard
|
||||
==============================
|
||||
.. include:: ../../README.rst
|
||||
Loading…
Reference in New Issue
Block a user