From fd7789403e82476fff3d2d73dcee0e3a1dcae0eb Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Wed, 27 Aug 2014 14:10:16 -0400 Subject: [PATCH] Doc cleanup Turn on warnerrors and fix the errors it reports. Change-Id: I92a194e47b97dbdeb0e72164a813f41914f4f298 --- doc/source/_static/.placeholder | 0 doc/source/cacti.rst | 4 ++-- doc/source/elastic-recheck.rst | 2 +- doc/source/gerrit.rst | 10 ++++------ doc/source/logstash.rst | 5 ++++- doc/source/openstackid.rst | 11 ++++++----- doc/source/running-your-own.rst | 22 +++++++++++++--------- doc/source/stackforge.rst | 2 ++ doc/source/systems.rst | 10 ++++++++++ doc/source/third_party.rst | 21 +++++++++++++++------ setup.cfg | 3 +++ tox.ini | 3 +++ 12 files changed, 63 insertions(+), 30 deletions(-) create mode 100644 doc/source/_static/.placeholder diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder new file mode 100644 index 0000000000..e69de29bb2 diff --git a/doc/source/cacti.rst b/doc/source/cacti.rst index 4fd45e2502..0ed636218d 100644 --- a/doc/source/cacti.rst +++ b/doc/source/cacti.rst @@ -3,9 +3,9 @@ .. _cacti: Cacti -###### +##### -The `Cacti `_ network graphing tool +The `Cacti network graphing tool `_ is installed on cacti.openstack.org. At a Glance diff --git a/doc/source/elastic-recheck.rst b/doc/source/elastic-recheck.rst index 2f801f9816..be8810c4a0 100644 --- a/doc/source/elastic-recheck.rst +++ b/doc/source/elastic-recheck.rst @@ -3,7 +3,7 @@ .. _elastic-recheck: Elastic-Recheck -###### +############### diff --git a/doc/source/gerrit.rst b/doc/source/gerrit.rst index 7040e9ddbc..7e21ae9409 100644 --- a/doc/source/gerrit.rst +++ b/doc/source/gerrit.rst @@ -501,11 +501,11 @@ or manually update their remotes with something like:: Third-Party Testing Access -------------------------- -The command to add an account for an automated system which gets --1/+1 code verify voting rights (as outlined in `Third Party -Testing`_) looks like: +The command to add an account for an automated system which gets -1/+1 +code verify voting rights (as outlined in :ref:`third-party-testing`) +looks like: -.. code-block:: shell +.. code-block:: bash ssh -p 29418 review.openstack.org "gerrit create-account \ --group 'Third-Party CI' \ @@ -517,8 +517,6 @@ Testing`_) looks like: Details on the create-account_ command can be found in the Gerrit API documentation. -.. _`Third-Party CI`: http://ci.openstack.org/third_party.html - .. _create-account: https://review.openstack.org/Documentation/cmd-create-account.html Resetting a Username in Gerrit diff --git a/doc/source/logstash.rst b/doc/source/logstash.rst index 788b985f0c..bc7525fe63 100644 --- a/doc/source/logstash.rst +++ b/doc/source/logstash.rst @@ -271,7 +271,10 @@ In the OpenStack logstash system, crm114 attaches an error_pr attribute to all indexed entries. Values from -1000.00 to -10.00 should be considered sufficient to get all potential errors as identified by the program. Used in a kibana query, it would be structured like this: - * ``error_pr:["-1000.0" TO "-10.0"]`` + +:: + + error_pr:["-1000.0" TO "-10.0"] This is still an early effort and additional tuning and refinement should diff --git a/doc/source/openstackid.rst b/doc/source/openstackid.rst index 7637107fde..d4e89626e2 100644 --- a/doc/source/openstackid.rst +++ b/doc/source/openstackid.rst @@ -1,4 +1,5 @@ :title: OpenstackId + ================== OpenstackId Server ================== @@ -37,15 +38,15 @@ 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. -.. code:: php +.. code-block:: php -detectEnvironment(array( + $env = $app->detectEnvironment(array( - 'local' => array('your-machine-name'), + 'local' => array('your-machine-name'), -)); + )); Database Configuration ______________________ diff --git a/doc/source/running-your-own.rst b/doc/source/running-your-own.rst index d6837da565..8d12d276e2 100644 --- a/doc/source/running-your-own.rst +++ b/doc/source/running-your-own.rst @@ -235,15 +235,17 @@ 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): - ssh-keygen -t rsa -P '' -f zuul_ssh_key + :: - cat zuul_ssh_key.pub | ssh -p 29418 $USER@$HOST gerrit create-account \ - --group "'Continuous Integration Tools'" \ - --full-name "'Zuul'" \ - --email zuul@lists.openstack.org \ - --ssh-key - zuul + ssh-keygen -t rsa -P '' -f zuul_ssh_key + + cat zuul_ssh_key.pub | ssh -p 29418 $USER@$HOST gerrit create-account \ + --group "'Continuous Integration Tools'" \ + --full-name "'Zuul'" \ + --email zuul@lists.openstack.org \ + --ssh-key - zuul #. Add the private key you made to hiera as ``zuul_ssh_private_key_contents``. @@ -280,9 +282,11 @@ important). When doing bring-up, bringing up jenkins01 first is probably best as that is the first of the horizontally-scalable untrusted masters, which get the most load (as they run jobs from anyone). -#. Make a jenkins master ssh key (shared across all jenkins masters):: +#. Make a jenkins master ssh key (shared across all jenkins masters): - ssh-keygen -t rsa -P '' -f jenkins_ssh_key + :: + + ssh-keygen -t rsa -P '' -f jenkins_ssh_key #. Make a self signed certificate for the jenkins site. diff --git a/doc/source/stackforge.rst b/doc/source/stackforge.rst index c47bb09826..5af4f73fca 100644 --- a/doc/source/stackforge.rst +++ b/doc/source/stackforge.rst @@ -1,5 +1,7 @@ :title: StackForge +.. _stackforge: + StackForge ########## diff --git a/doc/source/systems.rst b/doc/source/systems.rst index ec034f1e83..80b604c10c 100644 --- a/doc/source/systems.rst +++ b/doc/source/systems.rst @@ -28,4 +28,14 @@ Major Systems git openstackid +.. NOTE(dhellmann): These projects were not listed above, or in any + other toctree, which breaks the build. It's not clear why they were + left out of the toctree but remained in the source dir. Rather than + deleting them, I've added them to a hidden toctree to eliminate + that build error. +.. toctree:: + :hidden: + + activity + asterisk diff --git a/doc/source/third_party.rst b/doc/source/third_party.rst index f98162bc8b..e450ffadf0 100644 --- a/doc/source/third_party.rst +++ b/doc/source/third_party.rst @@ -1,3 +1,5 @@ +.. _third-party-testing: + Third Party Testing =================== @@ -44,7 +46,7 @@ Requirements `_ to add your system. When complete, there should be a page dedicated to your system with a URL like: - . + ``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. @@ -64,7 +66,8 @@ Requirements * logs must be browsable; logs requiring download, installation or login to access are not acceptable - Note: all test artifacts must be retained for one month. + + .. note:: All test artifacts must be retained for one month. Reading the Event Stream ------------------------ @@ -177,9 +180,11 @@ processes described in this document. So if your testing system is Jenkins based you can use it to simplify things. You will still need an account to do this as described in the :ref:`request-account-label` section above. -The Gerrit Trigger plugin for Jenkins can be found on -`the Jenkins repository `_. -You can install it using the Advanced tab in the Jenkins Plugin Manager. +The Gerrit Trigger plugin for Jenkins can be found on `the Jenkins +repository`_. You can install it using the Advanced tab in the +Jenkins Plugin Manager. + +.. _the Jenkins repository: http://repo.jenkins-ci.org/repo/com/sonyericsson/hudson/plugins/gerrit/gerrit-trigger/ Once installed Jenkins will have a new `Gerrit Trigger` option in the `Manage Jenkins` menu. This should be given the following options:: @@ -246,9 +251,11 @@ Permissions on your Third Party System When your CI account is created it will be in the `Third-Party CI Gerrit group `_. The permissions on this group allow for commenting and voting on the -`openstack-dev/sandbox `_ +`openstack-dev/sandbox`_ repo as well as commenting without voting on other repos in gerrit. +.. _openstack-dev/sandbox: https://git.openstack.org/cgit/openstack-dev/sandbox/ + 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 @@ -273,9 +280,11 @@ chance of success if you follow these steps: * 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 + * present your account history * address any questions and concerns with your system diff --git a/setup.cfg b/setup.cfg index 8019e24b1b..b85de267ac 100644 --- a/setup.cfg +++ b/setup.cfg @@ -18,3 +18,6 @@ classifier = all_files = 1 build-dir = doc/build source-dir = doc/source + +[pbr] +warnerrors = true diff --git a/tox.ini b/tox.ini index 34f9788932..a84b0f7d1e 100644 --- a/tox.ini +++ b/tox.ini @@ -28,6 +28,9 @@ commands = {toxinidir}/tools/check_projects_yaml_alphabetized.sh [testenv:venv] commands = {posargs} +[testenv:docs] +commands = python setup.py build_sphinx + [testenv:irc] deps = PyYAML irc