From 1a3aa9a0541337f5ee11d85fb797c7915c83fc9b Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Wed, 27 Aug 2014 21:44:22 +0200 Subject: [PATCH] Fix doc8 issues Remove extra whitespace. Wrap overlong lines. Remove extra ".." in one place Change-Id: Ib7280a87ddb663a8ab27308ffd67d19f0b0f7b09 --- doc/source/gerrit.rst | 3 +- doc/source/irc.rst | 10 ++-- doc/source/jenkins.rst | 4 +- doc/source/jjb.rst | 9 ++-- doc/source/openstackid.rst | 58 ++++++++++++++-------- doc/source/puppet.rst | 8 ++-- doc/source/running-your-own.rst | 18 ++++--- doc/source/third_party.rst | 85 +++++++++++++++++++-------------- 8 files changed, 118 insertions(+), 77 deletions(-) diff --git a/doc/source/gerrit.rst b/doc/source/gerrit.rst index f2c7a82115..dea9a23f84 100644 --- a/doc/source/gerrit.rst +++ b/doc/source/gerrit.rst @@ -228,7 +228,8 @@ SSH because it's fast, and it gets syntax checked). #. Visit ``https://$HOST/#/admin/projects/All-Projects,access`` and click on Edit. -#. Look for the reference to 'refs/meta/config', click on the drop-box for 'add permission' and choose 'PUSH'. +#. Look for the reference to 'refs/meta/config', click on the drop-box + for 'add permission' and choose 'PUSH'. #. Type in Administrators as the group name diff --git a/doc/source/irc.rst b/doc/source/irc.rst index 6305974b6e..65dd839112 100644 --- a/doc/source/irc.rst +++ b/doc/source/irc.rst @@ -67,8 +67,8 @@ Supybot In order to run Meetbot you will need to get Supybot. You can find the latest release `here `_. Once you have extracted the release you will want to read the ``INSTALL`` and -``doc/GETTING_STARTED`` files. Those two files should have enough information to -get you going, but there are other goodies in ``doc/``. +``doc/GETTING_STARTED`` files. Those two files should have enough +information to get you going, but there are other goodies in ``doc/``. Once you have Supybot installed you will need to configure a bot. The ``supybot-wizard`` command can get you started with a basic config, or you can @@ -142,9 +142,9 @@ Logging Meetings are automatically logged and published at http://eavesdrop.openstack.org/meetings/ -The bot also has the ability to sit in a channel for the sole purpose of logging -channel activity, not just meetings. Standard channel logs are sent to -http://eavesdrop.openstack.org/irclogs/ +The bot also has the ability to sit in a channel for the sole purpose +of logging channel activity, not just meetings. Standard channel logs +are sent to http://eavesdrop.openstack.org/irclogs/ The configuration for specific channel logging can be found in :file:`modules/openstack_project/manifests/eavesdrop.pp`. diff --git a/doc/source/jenkins.rst b/doc/source/jenkins.rst index 33574457e7..73ebee7173 100644 --- a/doc/source/jenkins.rst +++ b/doc/source/jenkins.rst @@ -113,8 +113,8 @@ hand: #. Login. -#. Setup matrix security: add the 'authenticated' pseudo user and - grant Admin access to your own user. +#. Setup matrix security: add the 'authenticated' pseudo user and + grant Admin access to your own user. #. Setup one account per `http://ci.openstack.org/jenkins-job-builder/installation.html#configuration-file` and grab the API token for it. diff --git a/doc/source/jjb.rst b/doc/source/jjb.rst index 7b507060d1..7e96bd41b6 100644 --- a/doc/source/jjb.rst +++ b/doc/source/jjb.rst @@ -48,8 +48,9 @@ yaml config files: * Jenkins Jobs Macros to give larger config sections meaningful names in ``macros.yaml``. * Project specific configurations in ``project_name.yaml``. -* Job template configurations. Need a ``projects.yaml`` file to specify how - the templates should be filled out and templates go in ``template_name.yaml``. +* Job template configurations. Need a ``projects.yaml`` file to + specify how the templates should be filled out and templates go in + ``template_name.yaml``. YAML Format =========== @@ -246,8 +247,8 @@ Job Caching The Jenkins Jobs builder maintains a special `cache`_ that contains an MD5 of every generated XML that it builds. If it finds the XML is different then it will proceed to send this -to Jenkins, otherwise it is skipped. If a job is accidentally deleted then this -file should be modified or removed. +to Jenkins, otherwise it is skipped. If a job is accidentally deleted +then this file should be modified or removed. .. _cache: http://ci.openstack.org/jenkins-job-builder/installation.html#running diff --git a/doc/source/openstackid.rst b/doc/source/openstackid.rst index d4e89626e2..0e01ad39bb 100644 --- a/doc/source/openstackid.rst +++ b/doc/source/openstackid.rst @@ -28,15 +28,18 @@ Configuration Environment Configuration _________________________ -We need to instruct the Laravel Framework how to determine which environment it is running in. The default environment -is always production. However, you may setup other environments within the *bootstrap/start.php* file at the root of -your installation. +We need to instruct the Laravel Framework how to determine which +environment it is running in. The default environment is always +production. However, you may setup other environments within the +*bootstrap/start.php* file at the root of your installation. It is include on folder bootstrap a file called bootstrap/environment.php.tpl you must make a copy and rename it to bootstrap/environment.php -In this file you will find an **$app->detectEnvironment** call. The array passed to this method is -used to determine the current environment. You may add other environments and machine names to the array as needed. +In this file you will find an **$app->detectEnvironment** call. The +array passed to this method is used to determine the current +environment. You may add other environments and machine names to the +array as needed. .. code-block:: php @@ -51,25 +54,37 @@ used to determine the current environment. You may add other environments and ma Database Configuration ______________________ -It is often helpful to have different configuration values based on the environment the application is running in. For example, you may wish to use a different database configuration on your development machine than on the production server. It is easy to accomplish this using environment based configuration. -Simply create a folder within the config directory that matches your environment name, such as **dev**. Next, create the configuration files you wish to override and specify the options for that environment. For example, to override the database configuration for the local environment, you would create a database.php file in app/config/dev. +It is often helpful to have different configuration values based on +the environment the application is running in. For example, you may +wish to use a different database configuration on your development +machine than on the production server. It is easy to accomplish this +using environment based configuration. +Simply create a folder within the config directory that matches your +environment name, such as **dev**. Next, create the configuration +files you wish to override and specify the options for that +environment. For example, to override the database configuration for +the local environment, you would create a database.php file in +app/config/dev. OpenstackId server makes use of two database connections: * openstackid * os_members -**openstackid** is its own OpenstackId Server DB, where stores all related configuration to openid/oauth2 protocol. +**openstackid** is its own OpenstackId Server DB, where stores all +related configuration to openid/oauth2 protocol. **os_members** is SS DB (http://www.openstack.org/). -both configuration are living on config file **database.php**, which could be a set per environment as forementioned -like app/config/dev/database.php +both configuration are living on config file **database.php**, which +could be a set per environment as forementioned like +app/config/dev/database.php Error Log Configuration _______________________ -Error log configuration is on file *app/config/log.php* but could be overridden per environment -such as *app/config/dev/log.php* , here you set two variables: +Error log configuration is on file *app/config/log.php* but could be +overridden per environment such as *app/config/dev/log.php* , here you +set two variables: * to_email : The receiver of the error log email. * from_email: The sender of the error log email. @@ -78,16 +93,20 @@ such as *app/config/dev/log.php* , here you set two variables: Recaptcha Configuration _______________________ -OpenstackId server uses recaptcha facility to discourage brute force attacks attempts on login page, so in order to work -properly recaptcha plugin must be provided with a public and a private key (http://www.google.com/recaptcha). -These keys are set on file *app/config/packages/greggilbert/recaptcha/config.php* , but also could be set per environment -using following directory structure *app/config/packages/greggilbert/recaptcha/dev/config.php*. +OpenstackId server uses recaptcha facility to discourage brute force +attacks attempts on login page, so in order to work properly recaptcha +plugin must be provided with a public and a private key +(http://www.google.com/recaptcha). These keys are set on file +*app/config/packages/greggilbert/recaptcha/config.php*, but also +could be set per environment using following directory structure +*app/config/packages/greggilbert/recaptcha/dev/config.php*. Installation ____________ -OpenstackId Server uses composer utility in order to install all needed dependencies. After you get the source code from git, -you must run following commands on application root directory: +OpenstackId Server uses composer utility in order to install all +needed dependencies. After you get the source code from git, you must +run following commands on application root directory: * curl -sS https://getcomposer.org/installer | php * php composer.phar install @@ -99,4 +118,5 @@ you must run following commands on application root directory: Permissions ___________ -Laravel may require one set of permissions to be configured: folders within app/storage require write access by the web server. +Laravel may require one set of permissions to be configured: folders +within app/storage require write access by the web server. diff --git a/doc/source/puppet.rst b/doc/source/puppet.rst index 96363f985e..c367a69338 100644 --- a/doc/source/puppet.rst +++ b/doc/source/puppet.rst @@ -76,14 +76,16 @@ file should have mode 0600. Adding a node ------------- -On the new server connecting (for example, review.openstack.org) to the puppet master: +On the new server connecting (for example, review.openstack.org) to +the puppet master: .. code-block:: bash sudo apt-get install puppet -The node then needs to be configured to set a fixed hostname and the hostname -of the puppet master with the following additions to ``/etc/puppet/puppet.conf``: +The node then needs to be configured to set a fixed hostname and the +hostname of the puppet master with the following additions to +``/etc/puppet/puppet.conf``: .. code-block:: ini diff --git a/doc/source/running-your-own.rst b/doc/source/running-your-own.rst index 8d12d276e2..dec727423d 100644 --- a/doc/source/running-your-own.rst +++ b/doc/source/running-your-own.rst @@ -18,7 +18,8 @@ another project. Requirements ============ -* You need a cloud of some sort, all our tooling is built for OpenStack clouds :). +* You need a cloud of some sort, all our tooling is built for + OpenStack clouds :). * A service account for your CI systems within that cloud/clouds. @@ -64,8 +65,8 @@ are scaled horizonally, thus the separation). To run your own infrastructure we recommend you copy the entire tree, delete any servers you won't run, and replace hostnames and class names with yours throughout. -Some templates can be used as-is by leaving their references to point within the -openstack_project tree. +Some templates can be used as-is by leaving their references to point +within the openstack_project tree. Bootstrapping ~~~~~~~~~~~~~ @@ -184,7 +185,8 @@ Migrate the manifests: * Contact store should be set to false as at this stage we don't have a secure store setup. - * Start with just local replication, plus github if you have a github organisation already. + * Start with just local replication, plus github if you have a + github organisation already. * Ditto starting without gerritbot. @@ -235,7 +237,8 @@ can now set up a scheduler. Once setup, new patches uploaded to gerrit should be picked up and have a zuul verification fail (with 'LOST' which indicates the Jenkins environment is gone). -#. Create a zuul user (the upstream site.pp uses jenkins for historical reasons): +#. Create a zuul user (the upstream site.pp uses jenkins for + historical reasons): :: @@ -361,8 +364,9 @@ gets their own puppet cert. The openstack/site.pp has a legacy setting for #. Go into the Jenkins config and press 'test connection' on the gearman config to register the new slave. -Now, if you push a change, zuul should pick it up and run it on jenkins, and you can -get onto the interesting thing of debugging why it fails. +Now, if you push a change, zuul should pick it up and run it on +jenkins, and you can get onto the interesting thing of debugging why +it fails. Later chapters will cover setting up the test storage servers so you can see build history without logging into Jenkins. diff --git a/doc/source/third_party.rst b/doc/source/third_party.rst index e22b744cde..4da8e16447 100644 --- a/doc/source/third_party.rst +++ b/doc/source/third_party.rst @@ -6,10 +6,11 @@ Third Party Testing Overview -------- -Gerrit has an event stream which can be subscribed to, using this it is possible -to test commits against testing systems beyond those supplied by OpenStack's -Jenkins setup. It is also possible for these systems to feed information back -into Gerrit and they can also leave non-gating votes on Gerrit review requests. +Gerrit has an event stream which can be subscribed to, using this it +is possible to test commits against testing systems beyond those +supplied by OpenStack's Jenkins setup. It is also possible for these +systems to feed information back into Gerrit and they can also leave +non-gating votes on Gerrit review requests. An example of one such system is `Smokestack `_. Smokestack reads the Gerrit event stream and runs its own tests on the commits. @@ -49,7 +50,8 @@ Requirements ``https://wiki.openstack.org/wiki/ThirdPartySystems/Example``. * All comments from your CI system must contain a link to the wiki page for your CI system. - * Maintainers are encouraged to be in IRC regularly to make it faster to contact them. + * Maintainers are encouraged to be in IRC regularly to make it + faster to contact them. * Include a public link to all test artifacts to make debugging failed tests easier (using a dns name over a hardcoded ip is recommended). This should include: @@ -82,8 +84,9 @@ For example: $ ssh -p 29418 USERNAME@review.openstack.org gerrit stream-events -Will give a stream with an output like this (line breaks and indentation added -in this document for readability, the read JSON will be all one line per event): +Will give a stream with an output like this (line breaks and +indentation added in this document for readability, the read JSON will +be all one line per event): .. code-block:: javascript @@ -108,11 +111,12 @@ Further documentation on how to use the events stream can be found in `Gerrit's Posting Result To Gerrit ------------------------ -External testing systems can give non-gating votes to Gerrit by means of a -1/+1 -verify vote. OpenStack Jenkins has extra permissions to give a +2/-2 verify -vote which is gating. Comments should also be provided to explain what kind of -test failed.. We do also ask that the comments contain public links to the -failure so that the developer can see what caused the failure. +External testing systems can give non-gating votes to Gerrit by means +of a -1/+1 verify vote. OpenStack Jenkins has extra permissions to +give a +2/-2 verify vote which is gating. Comments should also be +provided to explain what kind of test failed. We do also ask that the +comments contain public links to the failure so that the developer can +see what caused the failure. An example of how to post this is as follows: @@ -120,8 +124,9 @@ An example of how to post this is as follows: $ ssh -p 29418 USERNAME@review.openstack.org gerrit review -m '"Test failed on MegaTestSystem "' --verified=-1 c0ff33 -In this example ``c0ff33`` is the commit ID for the review. You can set the -verified to either `-1` or `+1` depending on whether or not it passed the tests. +In this example ``c0ff33`` is the commit ID for the review. You can +set the verified to either `-1` or `+1` depending on whether or not it +passed the tests. Further documentation on the `review` command in Gerrit can be found in the `Gerrit review documentation page `_. @@ -161,11 +166,13 @@ following information is necessary: 1. The public SSH key described above (if using OpenSSH, this would be the full contents of the account's ~/.ssh/id_rsa.pub file after running 'ssh-keygen'). You can attach it to the email or include a hyperlink to - where you've published it so it can be retrieved. This is a non-sensitive piece - of data, and it's safe for it to be publicly visible. + where you've published it so it can be retrieved. This is a + non-sensitive piece of data, and it's safe for it to be publicly + visible. - 2. Your company/organization name or acronym. If you don't have a company name - please identify this in your email, we will need to find an equivalent. + 2. Your company/organization name or acronym. If you don't have a + company name please identify this in your email, we will need to + find an equivalent. 3. What you are verifying: this could be a product, driver or application. @@ -228,8 +235,8 @@ should configure as follows:: Type: Path Pattern: ** -This job will now automatically trigger when a new patchset is uploaded and will -report the results to Gerrit automatically. +This job will now automatically trigger when a new patchset is +uploaded and will report the results to Gerrit automatically. Testing your CI setup --------------------- @@ -256,10 +263,11 @@ repo as well as commenting without voting on other repos in gerrit. The OpenStack Infrastructure team disables mis-behaving third-party ci accounts at its discretion. This documentation endeavours to outline specific circumstances that may lead to an account being disabled. There have been -times when third-party ci systems behave in ways we didn't envision and therefore -were unable to document prior to the event. If your third-party ci system has been -disabled, check your email - we probably tried to contact you, and join us in -the #openstack-infra irc channel on freenode to discuss your situation. +times when third-party ci systems behave in ways we didn't envision +and therefore were unable to document prior to the event. If your +third-party ci system has been disabled, check your email - we +probably tried to contact you, and join us in the #openstack-infra irc +channel on freenode to discuss your situation. In order to get your Third Pary CI account to have voting permissions on repos in gerrit in addition to ``openstack-dev/sandbox`` you have a greater @@ -269,23 +277,28 @@ chance of success if you follow these steps: above (this will create a history of activity associated with your account which will be evaluated when you apply for voting permissions). -* Post comments, that adhere to the "Requirements" listed above, that demonstrate - the format for your system communication to the repos you want your system to test. +* Post comments, that adhere to the "Requirements" listed above, that + demonstrate the format for your system communication to the repos + you want your system to test. -* Once your Third Party Account has a history on gerrit so that others can evaluate - your format for comments, and the stability of your voting pattern (in the sandbox repo): +* Once your Third Party Account has a history on gerrit so that others + can evaluate your format for comments, and the stability of your + voting pattern (in the sandbox repo): - * send an email to the openstack-dev mailing list nominating your system for voting - permissions + * send an email to the openstack-dev mailing list nominating your + system for voting permissions * openstack-dev@lists.openstack.org - * use tags [Infra][Nova] for the Nova program, please replace [Nova] with [Program], - where [Program] is the name of the program your CI account will test + * use tags [Infra][Nova] for the Nova program, please replace + [Nova] with [Program], where [Program] is the name of the + program your CI account will test * present your account history * address any questions and concerns with your system -* If the members of the program you want voting permissions from agree your system should be - able to vote, the ptl or a core-reviewer from the program communicates this decision to the - OpenStack Infrastructure team who will move your Third Party CI System to the `Voting - Third-Party CI Gerrit group `_. +* If the members of the program you want voting permissions from agree + your system should be able to vote, the ptl or a core-reviewer from + the program communicates this decision to the OpenStack + Infrastructure team who will move your Third Party CI System to the + `Voting Third-Party CI Gerrit group + `_.