Doc updates for project-config

Change-Id: Idffa13d5d1990f47e46fc5b711563949da78b6f8

doc/source/custom_roles.py

@@ -41,7 +41,32 @@ def file_role(name, rawtext, text, lineno, inliner,
 
     ref = ('https://git.openstack.org/cgit/openstack-infra/config/tree/%s'
            % text)
-    node = nodes.reference(rawtext, text, refuri=ref, **options)
+    linktext = 'config: %s' % text
+    node = nodes.reference(rawtext, linktext, refuri=ref, **options)
+    return [node], []
+
+
+def config_role(name, rawtext, text, lineno, inliner,
+                options={}, content=[]):
+    """Link a local path to a cgit file view.
+
+    Returns 2 part tuple containing list of nodes to insert into the
+    document and a list of system messages.  Both are allowed to be
+    empty.
+
+    :param name: The role name used in the document.
+    :param rawtext: The entire markup snippet, with role.
+    :param text: The text marked with the role.
+    :param lineno: The line number where rawtext appears in the input.
+    :param inliner: The inliner instance that called us.
+    :param options: Directive options for customization.
+    :param content: The directive content for customization.
+    """
+
+    ref = ('https://git.openstack.org/cgit/openstack-infra/'
+           'project-config/tree/%s' % text)
+    linktext = 'project-config: %s' % text
+    node = nodes.reference(rawtext, linktext, refuri=ref, **options)
     return [node], []
 
 
@@ -51,4 +76,5 @@ def setup(app):
     :param app: Sphinx application context.
     """
     app.add_role('file', file_role)
+    app.add_role('config', config_role)
     return

doc/source/gerrit.rst

@@ -25,7 +25,7 @@ At a Glance
   * :file:`modules/openstack_project/manifests/review_dev.pp`
 :Configuration:
   * :file:`modules/openstack_project/templates/review.projects.ini.erb`
-  * :file:`modules/openstack_project/files/review.projects.yaml`
+  * :config:`gerrit/projects.yaml`
 :Projects:
   * http://code.google.com/p/gerrit/
 :Bugs:

doc/source/irc.rst

@@ -22,7 +22,7 @@ At a Glance
   * :file:`modules/openstack_project/manifests/eavesdrop.pp`
   * :file:`modules/openstack_project/manifests/review.pp`
 :Configuration:
-  * :file:`modules/gerritbot/files/gerritbot_channel_config.yaml`
+  * :config:`gerritbot/channels.yaml`
 :Projects:
   * http://wiki.debian.org/MeetBot
   * http://sourceforge.net/projects/supybot/
@@ -189,8 +189,7 @@ Gerritbot watches the Gerrit event stream (using the "stream-events"
 Gerrit command) and announces events (such as patchset-created, or
 change-merged) to relevant IRC channels.
 
-Gerritbot's configuration is in
+Gerritbot's configuration is in :config:`gerritbot/channels.yaml`
-:file:`modules/gerritbot/files/gerritbot_channel_config.yaml`.
 
 Teams can add their channel and go through the standard code review process to
 get the bot added to their channel. The configuration is organized by channel,

doc/source/jeepyb.rst

@@ -21,7 +21,7 @@ At a Glance
   * :file:`modules/openstack_project/manifests/review_dev.pp`
 :Configuration:
   * :file:`modules/openstack_project/templates/review.projects.ini.erb`
-  * :file:`modules/openstack_project/files/review.projects.yaml`
+  * :config:`gerrit/projects.yaml`
   * :file:`modules/openstack_project/files/pypi-mirror.yaml`
 :Projects:
   * https://git.openstack.org/cgit/openstack-infra/jeepyb
@@ -56,9 +56,8 @@ connect to things or how to operate is in
      has-downloads=False
 
 OpenStack Gerrit projects are configured in the
-:file:`modules/openstack_project/files/review.projects.yaml`.
+:config:`gerrit/projects.yaml`.  file.  When this file is updated,
-file.  When this file is updated, ``manage-projects`` is run
+``manage-projects`` is run automatically.
-automatically.
 
 #. Project definition::
 
@@ -70,20 +69,19 @@ automatically.
        has-wiki: True
        acl-config: /path/to/acl/file
 
-The above config gives puppet and its related scripts enough information
+The above config gives puppet and its related scripts enough
-to create new projects, but not enough to add access controls to each
+information to create new projects, but not enough to add access
-project. To add access control you need to have an ``acl-config``
+controls to each project. To add access control you need to have an
-option for the project in ``review.projects.yaml`` file. That option
+``acl-config`` option for the project in ``projects.yaml``. That
-should have a value that is a path to the ``project.config`` for that
+option should have a value that is a path to the ``project.config``
-project.
+for that project.
 
 That is the high level view of how we can configure projects using the
 pupppet repository. To create an actual change that does all of this for
 a single project you will want to do the following:
 
-#. Add a
+#. Add a ``gerrit/acls/project-name.config`` file to the
-   ``modules/openstack_project/files/gerrit/acls/project-name.config``
+   ``project-config`` repo. The contents will probably end up looking like
-   file to the repo. The contents will probably end up looking like
    the block below (note that the sections are in alphabetical order
    and each indentation is 8 spaces)::
 
@@ -102,8 +100,8 @@ a single project you will want to do the following:
      [submit]
      mergeContent = true
 
-#. Add a project entry for the project in
+#. Add a project entry for the project in ``gerrit/projects.yaml`` in
-   ``modules/openstack_project/files/review.projects.yaml``.::
+   the ``project-config`` repo.::
 
      - project: openstack/project-name
        acl-config: /home/gerrit2/acls/project-name.config

doc/source/jjb.rst

@@ -17,7 +17,7 @@ At a Glance
 :Puppet:
   * :file:`modules/jenkins/manifests/job_builder.pp`
 :Configuration:
-  * :file:`modules/openstack_project/files/jenkins_job_builder/config/`
+  * :config:`jenkins/jobs/`
 :Projects:
   * https://git.openstack.org/cgit/openstack-infra/jenkins-job-builder
 :Bugs:
@@ -28,7 +28,7 @@ At a Glance
 Overview
 ========
 
-In order to make the process of managing hundreds of Jenkins jobs
+In order to make the process of managing thousands of Jenkins jobs
 easier, Jenkins Job Builder was designed to take YAML based
 configurations and convert those into jobs that are injected into
 Jenkins.
@@ -40,9 +40,9 @@ Configuring Projects
 ====================
 
 The YAML scripts to make this work are stored in the
-:file:`modules/openstack_project/files/jenkins_job_builder/config/`
+:config:`jenkins/jobs/` directory of the project-config repository.
-directory.  In this directory you can have four different types of
+In this directory you can have four different types of yaml config
-yaml config files:
+files:
 
 * Jenkins Jobs Defaults in ``defaults.yaml``.
 * Jenkins Jobs Macros to give larger config sections meaningful names in
@@ -64,19 +64,6 @@ Example defaults config:
 
    - defaults:
        name: global
-       description: |
-         <p><b>This job is managed by puppet and will be overwritten.</b></p>
-
-         <p><b>Do not edit this job through the web</b></p>
-
-         <p>If you would like to make changes to this job, please see:
-
-           <a href="https://git.openstack.org/cgit/openstack-infra/config">
-             https://git.openstack.org/cgit/openstack-infra/config
-           </a>
-
-         In modules/openstack_project/files/jenkins_jobs
-         </p>
        project-type: freestyle
        concurrent: true
 

doc/source/nodepool.rst

@@ -19,7 +19,8 @@ At a Glance
   * :file:`modules/openstack_project/manifests/single_use_slave.pp`
 :Configuration:
   * :file:`modules/openstack_project/templates/nodepool/nodepool.yaml.erb`
-  * :file:`modules/openstack_project/files/nodepool/scripts/`
+  * :config:`nodepool/scripts/`
+  * :config:`nodepool/elements/`
 :Projects:
   * https://git.openstack.org/openstack-infra/nodepool
 :Bugs:

doc/source/running-your-own.rst

@@ -2,6 +2,8 @@
 
 .. _running-your-own:
 
+.. warning:: Parts of this file are out of date
+
 Running your own CI infrastructure
 ##################################
 

doc/source/stackforge.rst

@@ -46,15 +46,16 @@ Add a Project to StackForge
 Create a new StackForge Project with Puppet
 ===========================================
 
-OpenStack uses Puppet and a management script to create Gerrit projects
+OpenStack uses Puppet and a management script to create Gerrit
-with simple changes to the openstack-infra/config repository. To start make
+projects with simple changes to the openstack-infra/project-config
-sure you have cloned the openstack-infra/config repository
+repository. To start make sure you have cloned the
-``git clone https://git.openstack.org/openstack-infra/config``.
+openstack-infra/project-config repository ``git clone
+https://git.openstack.org/openstack-infra/project-config``.
 
-First you need to add your StackForge project to the master project list.
+First you need to add your StackForge project to the master project
-Edit ``modules/openstack_project/files/review.projects.yaml`` and add a
+list.  Edit :config:`gerrit/projects.yaml` and add a new section for
-new section for your project in alphabetical order within the file.
+your project in alphabetical order within the file.  It should look
-It should look something like::
+something like::
 
   - project: stackforge/project-name
     description: Latest and greatest cloud stuff.
@@ -72,8 +73,7 @@ unnecessary branches and tags after the merge requires an openstack-infra
 core member to do so.
 
 The next step is to add a Gerrit ACL config file. Edit
-``modules/openstack_project/files/gerrit/acls/stackforge/project-name.config``
+``gerrit/acls/stackforge/project-name.config`` and make it look like::
-and make it look like::
 
   [access "refs/heads/*"]
   abandon = group project-name-core
@@ -108,15 +108,15 @@ these additional tools.
 Add Jenkins Jobs to StackForge Projects
 =======================================
 
-In the same openstack-infra/config repository (and in the same change
+In the same openstack-infra/project-config repository (and in the same
-if you like) we need to edit additional files to setup Jenkins jobs
+change if you like) we need to edit additional files to setup Jenkins
-and Zuul for the new StackForge project.
+jobs and Zuul for the new StackForge project.
 
 If you are interested in using the standard python Jenkins jobs (docs,
 pep8, python 2.6 and 2.7 unittests, and coverage), edit
-``modules/openstack_project/files/jenkins_job_builder/config/projects.yaml``
+:config:`jenkins/jobs/projects.yaml` and add a new section for your
-and add a new section for your project in alphabetical order in the file. It
+project in alphabetical order in the file. It should look something
-should look something like::
+like::
 
   - project:
       name: project-name
@@ -127,10 +127,10 @@ should look something like::
         - python-jobs
 
 List of jobs included to the ``python-jobs`` jobs group is located in
-``modules/openstack_project/files/jenkins_job_builder/config/python-jobs.yaml``.
+:config:`jenkins/jobs/python-jobs.yaml`.  For document publication
-For document publication there's also a publisher job template for the
+there's also a publisher job template for the popular `Read the Docs`_
-popular `Read the Docs`_ documentation hosting service, which can be
+documentation hosting service, which can be used by adding the
-used by adding the ``hook-{name}-rtfd`` template to the jobs list::
+``hook-{name}-rtfd`` template to the jobs list::
 
   - project:
       name: project-name
@@ -147,10 +147,9 @@ If you aren't ready to run any gate tests or other project-specific
 jobs yet, you don't need to edit ``projects.yaml``.
 
 Now that we have Jenkins jobs we need to tell Zuul to run them when
-appropriate. Edit
+appropriate. Edit :config:`zuul/layout.yaml` and add a new section for
-``modules/openstack_project/files/zuul/layout.yaml``
+your project in alphabetical order within the file.  It should look
-and add a new section for your project in alphabetical order within the file.
+something like::
-It should look something like::
 
   - name: stackforge/project-name
     template:
@@ -159,17 +158,17 @@ It should look something like::
       - name: python3-jobs
 
 If you aren't ready to run any gate tests yet and did not configure
-python-jobs in projects.yaml, it should look like this instead::
+python-jobs in ``projects.yaml``, it should look like this instead::
 
   - name: stackforge/project-name
     template:
       - name: merge-check
       - name: noop-jobs
 
-That concludes the bare minimum openstack-infra/config changes necessary to
+That concludes the bare minimum openstack-infra/project-config changes
-add a project to StackForge. You can commit these changes and submit
+necessary to add a project to StackForge. You can commit these changes
-them to review.openstack.org at this point, or you can wait a little
+and submit them to review.openstack.org at this point, or you can wait
-longer and add your project to GerritBot first.
+a little longer and add your project to GerritBot first.
 
 Request an Initial Gerrit Core Group Member
 ===========================================
@@ -190,12 +189,10 @@ project group management.
 Configure StackForge Project to use GerritBot
 =============================================
 
-To have GerritBot send Gerrit events for your project to a Freenode IRC
+To have GerritBot send Gerrit events for your project to a Freenode
-channel edit
+IRC channel edit :config:`gerritbot/channels.yaml`.  If you want to
-``modules/gerritbot/files/gerritbot_channel_config.yaml``.
+configure GerritBot to leave alerts in a channel GerritBot has always
-If you want to configure GerritBot to leave alerts in a channel
+joined just add your project to the project list for that channel::
-GerritBot has always joined just add your project to the project list
-for that channel::
 
   stackforge-dev:
       events:
@@ -223,11 +220,10 @@ end of this file that looks like::
         - master
 
 If you are defining a new channel, add it also in
-``modules/openstack_project/files/accessbot/channels.yaml`` file, optionally
+:config:`accessbot/channels.yaml` file, optionally defining also its
-defining also its mask.
+mask.  The mask will be used to define the access level for IRC users
-The mask will be used to define the access level for IRC users who are not
+who are not listed in that file in the ``global`` section or otherwise
-listed in that file in the ``global`` section or otherwise listed for the
+listed for the channel.
-channel.
 
 For instance:
 

doc/source/static.rst

@@ -19,6 +19,8 @@ At a Glance
   * http://specs.openstack.org
 :Puppet:
   * :file:`modules/openstack_project/manifests/static.pp`
+:Configuration:
+  * :config:`specs/index.html`
 :Projects:
   * http://apache.org/
 :Bugs:

doc/source/zuul.rst

@@ -20,7 +20,7 @@ At a Glance
   * :file:`modules/openstack_project/manifests/zuul_prod.pp`
   * :file:`modules/openstack_project/manifests/zuul_dev.pp`
 :Configuration:
-  * :file:`modules/openstack_project/files/zuul/layout.yaml`
+  * :config:`zuul/layout.yaml`
 :Projects:
   * http://launchpad.net/zuul
   * https://git.openstack.org/cgit/openstack-infra/zuul
@@ -78,9 +78,8 @@ each commit is correctly tested.
 Zuul's current status may be viewed at
 `<http://status.openstack.org/zuul/>`_.
 
-Zuul's configuration is stored in
+Zuul's configuration is stored in :config:`zuul/layout.yaml`.  Anyone
-:file:`modules/openstack_project/files/zuul/layout.yaml`.  Anyone may
+may propose a change to the configuration by editing that file and
-propose a change to the configuration by editing that file and
 submitting the change to Gerrit for review.
 
 For the full syntax of Zuul's configuration file format, see the `Zuul