From 866e8a43ad700a9621898c17df333daf8b13a235 Mon Sep 17 00:00:00 2001 From: Anusha Ramineni Date: Fri, 30 Jun 2017 09:06:23 +0530 Subject: [PATCH] Update Index file documentation Change-Id: Ifaadcc99d79693dd5a72066e3507b7ee73eae79f --- doc/source/conf.py | 159 ++---------------------------------- doc/source/contributing.rst | 20 +++++ doc/source/index.rst | 95 +++++---------------- doc/source/readme.rst | 4 + setup.cfg | 4 + 5 files changed, 58 insertions(+), 224 deletions(-) create mode 100644 doc/source/contributing.rst create mode 100644 doc/source/readme.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 20849a9..c9e51ab 100644 --- a/doc/source/conf.py +++ b/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__)) -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 ------------------------------------------------- diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 0000000..da6aa66 --- /dev/null +++ b/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 + diff --git a/doc/source/index.rst b/doc/source/index.rst index 17af910..1b4706a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 + readme + Contributing +Indices and tables +================== +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/readme.rst b/doc/source/readme.rst new file mode 100644 index 0000000..6cc6001 --- /dev/null +++ b/doc/source/readme.rst @@ -0,0 +1,4 @@ +============================== +Installing Congress Dashboard +============================== +.. include:: ../../README.rst diff --git a/setup.cfg b/setup.cfg index 57db65f..a34619f 100644 --- a/setup.cfg +++ b/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