From 5dec41a35b335ae7c33ba5f3a8ab00e0d32ca0a8 Mon Sep 17 00:00:00 2001 From: venkatamahesh Date: Sat, 19 Sep 2015 00:04:34 +0530 Subject: [PATCH] Fix few typos Removed the extra underlines for headings and Renamed one readme.rst file Change-Id: I889b122689b2ff03b3bed77134fb59609c6b3995 --- CONTRIBUTING.rst | 5 +++-- HACKING.rst | 7 ++++--- doc/source/{readme.rst => README.rst} | 0 doc/source/api.rst | 14 +++++++------- doc/source/cloudservices.rst | 28 +++++++++++++-------------- doc/source/enforcement.rst | 12 ++++++------ doc/source/policy.rst | 23 +++++++++------------- doc/source/release.rst | 8 ++++---- doc/source/troubleshooting.rst | 10 +++++----- 9 files changed, 52 insertions(+), 55 deletions(-) rename doc/source/{readme.rst => README.rst} (100%) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 3efe2774d..30eb0d31d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,5 +1,6 @@ +============ Contributing -============= +============ The Congress wiki page is the authoritative starting point. @@ -21,4 +22,4 @@ Pull requests submitted through GitHub will be ignored. Bugs should be filed on Launchpad, not GitHub: - https://bugs.launchpad.net/congress \ No newline at end of file + https://bugs.launchpad.net/congress diff --git a/HACKING.rst b/HACKING.rst index 847e24794..f3e874ff0 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -1,4 +1,5 @@ -congress Style Commandments -=============================================== +=========================== +Congress style commandments +=========================== -Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/ \ No newline at end of file +Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/ diff --git a/doc/source/readme.rst b/doc/source/README.rst similarity index 100% rename from doc/source/readme.rst rename to doc/source/README.rst diff --git a/doc/source/api.rst b/doc/source/api.rst index 4abb8d70e..b83583181 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -21,7 +21,7 @@ There are two top-level concepts in today's API: Policies and Data-sources. 1. Policy (/v1/) -================= +================ You can create and delete policies. Two policies are provided by the system, and you are not permitted to delete them: *classification* @@ -59,7 +59,7 @@ more details and examples:: 2. Policy Rules (/v1/policies//...) -=============================================== +============================================== Each policy is a collection of rules. Congress supports the usual CRUD operations for changing that collection. A rule has the following fields: @@ -110,7 +110,7 @@ GET .../rows?trace=true List rows with explanation (use 'printf' to displ 5. DEPRECATED: Drivers (/v1/system/) -====================================== +==================================== A driver is a piece of code that once instantiated and configured interacts with a specific cloud service like Nova or Neutron. A driver has the following fields. @@ -129,7 +129,7 @@ API-level datasource management with configuration-level datasource management. 6. Data sources (/v1/) -======================== +====================== A data source is an instantiated and configured driver that interacts with a particular instance of a cloud service (like Nova or Neutron). You can construct multiple datasources using @@ -167,7 +167,7 @@ configuration-level datasource management. 7. Data source Tables (/v1/data-sources//...) -======================================================== +==================================================== Each data source maintains a collection of tables (very similar to a Policy). The list of available tables for each data source is available via the API. @@ -184,7 +184,7 @@ GET .../tables//spec Show a table schema 8. Data source Table Rows (/v1/data-sources//tables//...) -============================================================================ +========================================================================== The contents of each data source table (the rows of each table) can be queried via the API as well. A row has just a Data field, which is a list of values. @@ -198,7 +198,7 @@ GET .../rows List rows 9. Versions (/) -================ +=============== You can see the supported API versions. diff --git a/doc/source/cloudservices.rst b/doc/source/cloudservices.rst index 55aface59..ffa6f72bb 100644 --- a/doc/source/cloudservices.rst +++ b/doc/source/cloudservices.rst @@ -2,12 +2,12 @@ .. _cloudservices: -=============== +============== Cloud Services -=============== +============== 1. Congress Works With All Services -==================================== +=================================== Congress will work with any cloud service, as long as Congress can represent the service's state in *table* format. A table is a @@ -27,7 +27,7 @@ following table.:: ====================================== ========== 2. Drivers -==================================== +========== To plug a new service into Congress, you write a small piece of code, called a *driver*, that queries the new service (usually through API calls) @@ -104,7 +104,7 @@ API-level datasource management with configuration-level datasource management. 3. Currently Supported Drivers -==================================== +============================== Congress currently has drivers for each of the following services. Each driver has a differing degree of coverage for the available API calls. @@ -168,13 +168,13 @@ For example:: .. _datasource_driver: 4. Writing a Datasource Driver -==================================== +============================== This section is a tutorial for those of you interested in writing your own datasource driver. It can be safely skipped otherwise. 4.1 Implementing a Datasource Driver --------------------------------------- +------------------------------------ All the Datasource drivers extend the code found in:: @@ -228,13 +228,13 @@ The following steps detail how to implement a datasource driver. API results along with the tables that were generated. 4.2 Converting API results into Tables ------------------------------------------ +-------------------------------------- Since Congress requires the state of each dataservice to be represented as tables, we must convert the results of each API call (which may be comprised of dictionaries, lists, dictionaries embedded within lists, etc.) into tables. 4.2.1 Convenience translators -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Congress provides a translation method to make the translation from API results into tables convenient. The translation method takes a description of @@ -280,7 +280,7 @@ translate_objs() which is defined in congress/datasources/datasource_driver.py See congress/datasources/neutron_driver.py as an example. 4.2.2 Custom data conversion -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The convenience translators may be insufficient in some cases, for example, @@ -411,7 +411,7 @@ flatten that subobject into tables. *Note* : uuid* are congress generated uuids 4.3 Writing a Datasource driver test --------------------------------------- +------------------------------------ Once you've written a driver, you'll want to add a unit test for it. To help, this section describes how the unit test for the Glance driver works. Here are the relevant files. @@ -421,7 +421,7 @@ Once you've written a driver, you'll want to add a unit test for it. To help, t The test code has two methods: setUp() and test_update_from_datasource(). 4.3.1 Glance setup -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~ We begin our description with the setUp() method of the test. @@ -465,7 +465,7 @@ Next the test defines which value it wants .images.list() to retu 4.3.2 Glance test -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~ test_update_from_datasource() is the actual test, where we have the datasource driver grab the list of Glance images and translate them to tables. The test runs the update_from_datasource() method like normal except it ensures the return value of .images.list() is self.mock_images. @@ -516,7 +516,7 @@ At this point in the test, update_from_datasource() has already been run, so all 4.3.3 Glance test code in full -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: python diff --git a/doc/source/enforcement.rst b/doc/source/enforcement.rst index dc426c72c..c7a587b47 100644 --- a/doc/source/enforcement.rst +++ b/doc/source/enforcement.rst @@ -3,9 +3,9 @@ .. _enforcement: -=========================== +========================== Monitoring and Enforcement -=========================== +========================== Congress is given two inputs: the other cloud services in the datacenter and a policy describing the desired state of those @@ -17,7 +17,7 @@ to ensure that the actual state of the other cloud services is also a desired state (i.e. that the other services obey policy). 1. Monitoring -=========================== +============= Recall from :ref:`Policy ` that policy violations are represented with the table *error*. To ask Congress for a list of all policy violations, we simply ask it for the contents of the *error* table. @@ -58,7 +58,7 @@ contents of the error table. 2. Proactive Enforcement -===================================== +======================== Often we want policy to be enforced, not just monitored. *Proactive enforcement* is the term we use to mean preventing policy violations before they occur. Proactive enforcement requires having enforcement points in the @@ -222,7 +222,7 @@ description rules. 2.1 Simulation with Actions ------------------------------------------- +--------------------------- The downside to the simulation functionality just described is that the cloud service wanting to prevent policy violations would need to compute the @@ -312,7 +312,7 @@ d) **Mixing actions and state-changes**. Simulate changing 101:9 and adding val 3. Manual Reactive Enforcement -================================= +============================== Not all policies can be enforced proactively on all clouds, which means that sometimes the cloud will violate policy. Once policy violations happen, Congress can take action to transition the cloud back into one of the states permitted by policy. We call this diff --git a/doc/source/policy.rst b/doc/source/policy.rst index 3b7ca1fde..0162d7008 100644 --- a/doc/source/policy.rst +++ b/doc/source/policy.rst @@ -2,9 +2,9 @@ .. _policy: -======= +====== Policy -======= +====== 1. What Does a Policy Look Like =============================== @@ -99,7 +99,7 @@ the subject of research and development for decades. .. _datalog: 2. Datalog Policy Language -================================= +========================== As a policy writer, your goal is to define the contents of the *error* table, and in so doing to describe exactly those conditions that must be true @@ -129,7 +129,7 @@ go beyond toy examples. 2.1 Core Datalog Features ---------------------------- +------------------------- Since Datalog is entirely concerned with tables, it's not surprising that Datalog allows us to represent concrete tables directly in the language. @@ -229,7 +229,7 @@ These rules happen to have only one atom in each of their bodies, but there is no requirement for that. 2.2 Extended Datalog Features -------------------------------- +----------------------------- In addition writing basic rules with and/or/not, the version of Datalog used by Congress includes the features described in this section. @@ -313,7 +313,7 @@ We discuss this modal operator in greater detail in Section 3. 2.3 Datalog Syntax Restrictions ---------------------------------- +------------------------------- There are a number of syntactic restrictions on Datalog that are, for the most part, common sense. @@ -385,7 +385,7 @@ or the wrong column names. 2.4 Datalog builtins ------------------------ +-------------------- Here is a list of the currently supported builtins. A builtin that has N inputs means that the leftmost N columns are the inputs, and the @@ -447,7 +447,7 @@ datetime_equal(x, y) 2 True if x == y 3. Multiple Policies -===================== +==================== One of the goals of Congress is for several different people in an organization to collaboratively define a single, overarching policy that governs a cloud. @@ -501,7 +501,7 @@ populating policies. 3.1 Syntactic Restrictions for Multiple Policies --------------------------------------------------- +------------------------------------------------ There are a couple of additional syntactic restrictions imposed when using multiple policies. @@ -532,8 +532,3 @@ head of the rule:: Congress will stop you from inserting rules that violate these restrictions. - - - - - diff --git a/doc/source/release.rst b/doc/source/release.rst index bc16eb231..abdb00b5e 100644 --- a/doc/source/release.rst +++ b/doc/source/release.rst @@ -2,12 +2,12 @@ .. _release: -================ +============= Release Notes -================ +============= Liberty --------- +------- **Main updates** * Added datasource driver for Heat @@ -26,7 +26,7 @@ Liberty Kilo --------- +---- **Main features** diff --git a/doc/source/troubleshooting.rst b/doc/source/troubleshooting.rst index 246ced8d9..3a943885a 100644 --- a/doc/source/troubleshooting.rst +++ b/doc/source/troubleshooting.rst @@ -2,9 +2,9 @@ .. _troubleshooting: -=============================== +=============== Troubleshooting -=============================== +=============== So you've installed Congress with devstack as per the README, and now something is not behaving the way you think it should. @@ -35,7 +35,7 @@ of problems and tips for how to fix them. :: Policy-engine troubleshooting ---------------------------------- +----------------------------- Make sure the policy engine knows about the rules you think it knows about. It is possible that the policy engine rejected a rule because of a syntax @@ -283,7 +283,7 @@ not the rules. Datasource troubleshooting ---------------------------- +-------------------------- At this point, you believe the problem is with one of the datasources. The first thing to consider is whether Congress can properly connect to the associated cloud service. @@ -488,7 +488,7 @@ problems. Production troubleshooting ----------------------------- +-------------------------- Another class of problems arises most often in production deployments. Here we give a couple of problems encountered in production deployments