From e6d8b210cc416ed494b0b0248404e3e6d7ce337c Mon Sep 17 00:00:00 2001 From: David Shrewsbury Date: Wed, 8 Jan 2020 15:28:35 -0500 Subject: [PATCH] Documentation reorg Reorganizing docs as recommended in: https://www.divio.com/blog/documentation/ This is simply a reorganization of the existing documents and changes no content EXCEPT to correct the location of sphinx doc references. Expect followup changes to change document names (to reflect the new structure) and to move content from existing guides (e.g., to move the pipeline/project/job structure definitions out of the "Project Configuration" reference guide into their own reference documents for easier locatability). All documents are now located in either the "overview", "tutorials", "discussions", or "references" subdirectories to reflect the new structure presented to the user. Code examples and images are moved to "examples" and "images" root-level directories. Developer specific documents are located in the "references/developer" directory. Change-Id: I538ffd7409941c53bf42fe64b7acbc146023c1e3 --- doc/source/admin/index.rst | 23 ------- .../{admin => discussions}/components.rst | 0 doc/source/{user => discussions}/concepts.rst | 0 .../{user => discussions}/encryption.rst | 0 doc/source/{user => discussions}/gating.rst | 0 doc/source/{user => discussions}/index.rst | 14 ++-- .../tenant-scoped-rest-api.rst | 0 doc/source/{admin => discussions}/tenants.rst | 0 .../{admin => }/examples/docker-compose.yaml | 0 .../examples/etc_nodepool/nodepool.yaml | 0 .../{admin => }/examples/etc_zuul/main.yaml | 0 .../{admin => }/examples/etc_zuul/zuul.conf | 0 doc/source/{admin => }/examples/httpd.conf | 0 .../{admin => }/examples/logs-Dockerfile | 0 .../{admin => }/examples/node-Dockerfile | 0 .../pipelines/gerrit-reference-pipelines.yaml | 0 .../pipelines/pagure-reference-pipelines.yaml | 0 .../examples/playbooks/project.config | 0 .../roles/create_project/tasks/main.yaml | 0 .../{admin => }/examples/playbooks/setup.yaml | 0 .../playbooks/wait-to-start-gearman.sh | 0 .../examples/playbooks/wait-to-start.sh | 0 .../examples/test1/playbooks/testjob.yaml | 0 .../{admin => }/examples/test1/zuul.yaml | 0 .../zuul-config/playbooks/base/post-logs.yaml | 0 .../zuul-config/playbooks/base/post-ssh.yaml | 0 .../zuul-config/playbooks/base/pre.yaml | 0 .../examples/zuul-config/zuul.d/jobs.yaml | 0 .../examples/zuul-config/zuul.d/jobs2.yaml | 0 .../zuul-config/zuul.d/pipelines.yaml | 0 .../examples/zuul-config/zuul.d/projects.yaml | 0 .../admins}/centos7_setup.rst | 0 .../admins}/fedora27_setup.rst | 0 .../{admin => howtos/admins}/gerrit_setup.rst | 0 .../{admin => howtos/admins}/github_setup.rst | 0 doc/source/howtos/admins/index.rst | 9 +++ .../{admin => howtos/admins}/installation.rst | 0 .../admins}/nodepool_install.rst | 0 .../admins}/nodepool_openstack.rst | 0 .../admins}/nodepool_static.rst | 0 .../admins}/opensuse_leap15_setup.rst | 0 .../admins}/troubleshooting.rst | 0 .../admins}/zuul-from-scratch.rst | 0 .../{admin => howtos/admins}/zuul_install.rst | 0 doc/source/{user => howtos/users}/badges.rst | 0 .../users}/cross-project-gating.rst | 0 doc/source/howtos/users/index.rst | 9 +++ .../{user/howtos => howtos/users}/pti.rst | 0 .../{admin => }/images/become-select.png | Bin doc/source/{admin => }/images/check1-1002.png | Bin doc/source/{admin => }/images/check2-1002.png | Bin doc/source/{admin => }/images/confirm.png | Bin doc/source/{admin => }/images/email.png | Bin .../{admin => }/images/open-changes.png | Bin .../{admin => }/images/orig/become-select.png | Bin .../{admin => }/images/orig/check1-1002.png | Bin .../{admin => }/images/orig/check2-1002.png | Bin .../{admin => }/images/orig/confirm.png | Bin .../{admin => }/images/orig/open-changes.png | Bin .../{admin => }/images/orig/recheck-1002.png | Bin .../{admin => }/images/orig/register.png | Bin .../{admin => }/images/orig/review-1001.png | Bin .../{admin => }/images/orig/review-1003.png | Bin .../{admin => }/images/orig/settings.png | Bin .../{admin => }/images/orig/sign-in.png | Bin .../images/orig/sign-out-admin.png | Bin .../{admin => }/images/orig/sign-out-user.png | Bin .../{admin => }/images/orig/submit-1001.png | Bin doc/source/{admin => }/images/profile.png | Bin .../{admin => }/images/recheck-1002.png | Bin doc/source/{admin => }/images/register.png | Bin doc/source/{admin => }/images/review-1001.png | Bin doc/source/{admin => }/images/review-1003.png | Bin doc/source/{admin => }/images/sign-in.png | Bin .../{admin => }/images/sign-out-admin.png | Bin .../{admin => }/images/sign-out-user.png | Bin doc/source/{admin => }/images/sshkey.png | Bin doc/source/{admin => }/images/submit-1001.png | Bin doc/source/index.rst | 55 +++++++++++----- doc/source/{ => overview}/governance.rst | 0 doc/source/overview/index.rst | 9 +++ doc/source/{ => overview}/releasenotes.rst | 1 - .../{user => overview}/vulnerabilities.rst | 0 doc/source/{admin => references}/client.rst | 0 doc/source/{user => references}/config.rst | 2 +- .../{admin => references}/connections.rst | 0 .../{ => references}/developer/ansible.rst | 0 .../{ => references}/developer/datamodel.rst | 0 .../{ => references}/developer/docs.rst | 0 .../{ => references}/developer/drivers.rst | 0 .../{ => references}/developer/index.rst | 0 .../{ => references}/developer/javascript.rst | 0 .../developer/releasenotes.rst | 0 .../specs/container-build-resources.rst | 0 .../developer/specs/index.rst | 0 .../developer/specs/kubernetes-operator.rst | 0 .../{ => references}/developer/specs/logs.rst | 0 .../specs/multiple-ansible-versions.rst | 0 .../specs/tenant-scoped-admin-web-API.rst | 0 .../{ => references}/developer/testing.rst | 0 .../{ => references}/developer/triggers.rst | 0 .../{admin => references}/drivers/gerrit.rst | 2 +- .../{admin => references}/drivers/git.rst | 0 .../{admin => references}/drivers/github.rst | 0 .../{admin => references}/drivers/mqtt.rst | 0 .../{admin => references}/drivers/pagure.rst | 2 +- .../{admin => references}/drivers/smtp.rst | 0 .../{admin => references}/drivers/sql.rst | 0 .../{admin => references}/drivers/timer.rst | 0 .../{admin => references}/drivers/zuul.rst | 0 doc/source/{ => references}/glossary.rst | 0 doc/source/references/index.rst | 14 ++++ doc/source/{user => references}/jobs.rst | 0 .../{admin => references}/monitoring.rst | 0 doc/source/{user => references}/web.rst | 0 doc/source/tutorials/admins/index.rst | 7 ++ .../admins}/quick-start.rst | 62 +++++++++--------- doc/source/tutorials/users/index.rst | 5 ++ doc/source/user/client-user.rst | 1 - doc/source/user/howtos.rst | 12 ---- playbooks/quick-start/main.yaml | 6 +- 121 files changed, 132 insertions(+), 101 deletions(-) delete mode 100644 doc/source/admin/index.rst rename doc/source/{admin => discussions}/components.rst (100%) rename doc/source/{user => discussions}/concepts.rst (100%) rename doc/source/{user => discussions}/encryption.rst (100%) rename doc/source/{user => discussions}/gating.rst (100%) rename doc/source/{user => discussions}/index.rst (77%) rename doc/source/{admin => discussions}/tenant-scoped-rest-api.rst (100%) rename doc/source/{admin => discussions}/tenants.rst (100%) rename doc/source/{admin => }/examples/docker-compose.yaml (100%) rename doc/source/{admin => }/examples/etc_nodepool/nodepool.yaml (100%) rename doc/source/{admin => }/examples/etc_zuul/main.yaml (100%) rename doc/source/{admin => }/examples/etc_zuul/zuul.conf (100%) rename doc/source/{admin => }/examples/httpd.conf (100%) rename doc/source/{admin => }/examples/logs-Dockerfile (100%) rename doc/source/{admin => }/examples/node-Dockerfile (100%) rename doc/source/{admin => }/examples/pipelines/gerrit-reference-pipelines.yaml (100%) rename doc/source/{admin => }/examples/pipelines/pagure-reference-pipelines.yaml (100%) rename doc/source/{admin => }/examples/playbooks/project.config (100%) rename doc/source/{admin => }/examples/playbooks/roles/create_project/tasks/main.yaml (100%) rename doc/source/{admin => }/examples/playbooks/setup.yaml (100%) rename doc/source/{admin => }/examples/playbooks/wait-to-start-gearman.sh (100%) rename doc/source/{admin => }/examples/playbooks/wait-to-start.sh (100%) rename doc/source/{admin => }/examples/test1/playbooks/testjob.yaml (100%) rename doc/source/{admin => }/examples/test1/zuul.yaml (100%) rename doc/source/{admin => }/examples/zuul-config/playbooks/base/post-logs.yaml (100%) rename doc/source/{admin => }/examples/zuul-config/playbooks/base/post-ssh.yaml (100%) rename doc/source/{admin => }/examples/zuul-config/playbooks/base/pre.yaml (100%) rename doc/source/{admin => }/examples/zuul-config/zuul.d/jobs.yaml (100%) rename doc/source/{admin => }/examples/zuul-config/zuul.d/jobs2.yaml (100%) rename doc/source/{admin => }/examples/zuul-config/zuul.d/pipelines.yaml (100%) rename doc/source/{admin => }/examples/zuul-config/zuul.d/projects.yaml (100%) rename doc/source/{admin => howtos/admins}/centos7_setup.rst (100%) rename doc/source/{admin => howtos/admins}/fedora27_setup.rst (100%) rename doc/source/{admin => howtos/admins}/gerrit_setup.rst (100%) rename doc/source/{admin => howtos/admins}/github_setup.rst (100%) create mode 100644 doc/source/howtos/admins/index.rst rename doc/source/{admin => howtos/admins}/installation.rst (100%) rename doc/source/{admin => howtos/admins}/nodepool_install.rst (100%) rename doc/source/{admin => howtos/admins}/nodepool_openstack.rst (100%) rename doc/source/{admin => howtos/admins}/nodepool_static.rst (100%) rename doc/source/{admin => howtos/admins}/opensuse_leap15_setup.rst (100%) rename doc/source/{admin => howtos/admins}/troubleshooting.rst (100%) rename doc/source/{admin => howtos/admins}/zuul-from-scratch.rst (100%) rename doc/source/{admin => howtos/admins}/zuul_install.rst (100%) rename doc/source/{user => howtos/users}/badges.rst (100%) rename doc/source/{user/howtos => howtos/users}/cross-project-gating.rst (100%) create mode 100644 doc/source/howtos/users/index.rst rename doc/source/{user/howtos => howtos/users}/pti.rst (100%) rename doc/source/{admin => }/images/become-select.png (100%) rename doc/source/{admin => }/images/check1-1002.png (100%) rename doc/source/{admin => }/images/check2-1002.png (100%) rename doc/source/{admin => }/images/confirm.png (100%) rename doc/source/{admin => }/images/email.png (100%) rename doc/source/{admin => }/images/open-changes.png (100%) rename doc/source/{admin => }/images/orig/become-select.png (100%) rename doc/source/{admin => }/images/orig/check1-1002.png (100%) rename doc/source/{admin => }/images/orig/check2-1002.png (100%) rename doc/source/{admin => }/images/orig/confirm.png (100%) rename doc/source/{admin => }/images/orig/open-changes.png (100%) rename doc/source/{admin => }/images/orig/recheck-1002.png (100%) rename doc/source/{admin => }/images/orig/register.png (100%) rename doc/source/{admin => }/images/orig/review-1001.png (100%) rename doc/source/{admin => }/images/orig/review-1003.png (100%) rename doc/source/{admin => }/images/orig/settings.png (100%) rename doc/source/{admin => }/images/orig/sign-in.png (100%) rename doc/source/{admin => }/images/orig/sign-out-admin.png (100%) rename doc/source/{admin => }/images/orig/sign-out-user.png (100%) rename doc/source/{admin => }/images/orig/submit-1001.png (100%) rename doc/source/{admin => }/images/profile.png (100%) rename doc/source/{admin => }/images/recheck-1002.png (100%) rename doc/source/{admin => }/images/register.png (100%) rename doc/source/{admin => }/images/review-1001.png (100%) rename doc/source/{admin => }/images/review-1003.png (100%) rename doc/source/{admin => }/images/sign-in.png (100%) rename doc/source/{admin => }/images/sign-out-admin.png (100%) rename doc/source/{admin => }/images/sign-out-user.png (100%) rename doc/source/{admin => }/images/sshkey.png (100%) rename doc/source/{admin => }/images/submit-1001.png (100%) rename doc/source/{ => overview}/governance.rst (100%) create mode 100644 doc/source/overview/index.rst rename doc/source/{ => overview}/releasenotes.rst (86%) rename doc/source/{user => overview}/vulnerabilities.rst (100%) rename doc/source/{admin => references}/client.rst (100%) rename doc/source/{user => references}/config.rst (99%) rename doc/source/{admin => references}/connections.rst (100%) rename doc/source/{ => references}/developer/ansible.rst (100%) rename doc/source/{ => references}/developer/datamodel.rst (100%) rename doc/source/{ => references}/developer/docs.rst (100%) rename doc/source/{ => references}/developer/drivers.rst (100%) rename doc/source/{ => references}/developer/index.rst (100%) rename doc/source/{ => references}/developer/javascript.rst (100%) rename doc/source/{ => references}/developer/releasenotes.rst (100%) rename doc/source/{ => references}/developer/specs/container-build-resources.rst (100%) rename doc/source/{ => references}/developer/specs/index.rst (100%) rename doc/source/{ => references}/developer/specs/kubernetes-operator.rst (100%) rename doc/source/{ => references}/developer/specs/logs.rst (100%) rename doc/source/{ => references}/developer/specs/multiple-ansible-versions.rst (100%) rename doc/source/{ => references}/developer/specs/tenant-scoped-admin-web-API.rst (100%) rename doc/source/{ => references}/developer/testing.rst (100%) rename doc/source/{ => references}/developer/triggers.rst (100%) rename doc/source/{admin => references}/drivers/gerrit.rst (99%) rename doc/source/{admin => references}/drivers/git.rst (100%) rename doc/source/{admin => references}/drivers/github.rst (100%) rename doc/source/{admin => references}/drivers/mqtt.rst (100%) rename doc/source/{admin => references}/drivers/pagure.rst (99%) rename doc/source/{admin => references}/drivers/smtp.rst (100%) rename doc/source/{admin => references}/drivers/sql.rst (100%) rename doc/source/{admin => references}/drivers/timer.rst (100%) rename doc/source/{admin => references}/drivers/zuul.rst (100%) rename doc/source/{ => references}/glossary.rst (100%) create mode 100644 doc/source/references/index.rst rename doc/source/{user => references}/jobs.rst (100%) rename doc/source/{admin => references}/monitoring.rst (100%) rename doc/source/{user => references}/web.rst (100%) create mode 100644 doc/source/tutorials/admins/index.rst rename doc/source/{admin => tutorials/admins}/quick-start.rst (93%) create mode 100644 doc/source/tutorials/users/index.rst delete mode 100644 doc/source/user/client-user.rst delete mode 100644 doc/source/user/howtos.rst diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst deleted file mode 100644 index 5c23b6b0fc..0000000000 --- a/doc/source/admin/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -Administrator's Guide -===================== - -This guide is intended for administrators of Zuul systems. It covers -installation, operation, and the portion of Zuul configuration that -occurs outside of the projects upon which Zuul operates. Advanced -users may be interested in some of the concepts described here, as -well as understanding what features the underlying configuration -provides to in-project configuration. - -.. toctree:: - :maxdepth: 2 - - quick-start - installation - zuul-from-scratch - components - connections - tenants - monitoring - client - tenant-scoped-rest-api - troubleshooting diff --git a/doc/source/admin/components.rst b/doc/source/discussions/components.rst similarity index 100% rename from doc/source/admin/components.rst rename to doc/source/discussions/components.rst diff --git a/doc/source/user/concepts.rst b/doc/source/discussions/concepts.rst similarity index 100% rename from doc/source/user/concepts.rst rename to doc/source/discussions/concepts.rst diff --git a/doc/source/user/encryption.rst b/doc/source/discussions/encryption.rst similarity index 100% rename from doc/source/user/encryption.rst rename to doc/source/discussions/encryption.rst diff --git a/doc/source/user/gating.rst b/doc/source/discussions/gating.rst similarity index 100% rename from doc/source/user/gating.rst rename to doc/source/discussions/gating.rst diff --git a/doc/source/user/index.rst b/doc/source/discussions/index.rst similarity index 77% rename from doc/source/user/index.rst rename to doc/source/discussions/index.rst index fea0496f76..ef0b965fc6 100644 --- a/doc/source/user/index.rst +++ b/doc/source/discussions/index.rst @@ -1,5 +1,5 @@ -User's Guide -============ +Discussions +=========== This guide is for all users of Zuul. If you work on a project where Zuul is used to drive automation (whether that's testing proposed @@ -12,12 +12,8 @@ configure it to meet your needs. :maxdepth: 2 concepts + components gating - config - jobs + tenants encryption - web - client-user - badges - howtos - vulnerabilities + tenant-scoped-rest-api diff --git a/doc/source/admin/tenant-scoped-rest-api.rst b/doc/source/discussions/tenant-scoped-rest-api.rst similarity index 100% rename from doc/source/admin/tenant-scoped-rest-api.rst rename to doc/source/discussions/tenant-scoped-rest-api.rst diff --git a/doc/source/admin/tenants.rst b/doc/source/discussions/tenants.rst similarity index 100% rename from doc/source/admin/tenants.rst rename to doc/source/discussions/tenants.rst diff --git a/doc/source/admin/examples/docker-compose.yaml b/doc/source/examples/docker-compose.yaml similarity index 100% rename from doc/source/admin/examples/docker-compose.yaml rename to doc/source/examples/docker-compose.yaml diff --git a/doc/source/admin/examples/etc_nodepool/nodepool.yaml b/doc/source/examples/etc_nodepool/nodepool.yaml similarity index 100% rename from doc/source/admin/examples/etc_nodepool/nodepool.yaml rename to doc/source/examples/etc_nodepool/nodepool.yaml diff --git a/doc/source/admin/examples/etc_zuul/main.yaml b/doc/source/examples/etc_zuul/main.yaml similarity index 100% rename from doc/source/admin/examples/etc_zuul/main.yaml rename to doc/source/examples/etc_zuul/main.yaml diff --git a/doc/source/admin/examples/etc_zuul/zuul.conf b/doc/source/examples/etc_zuul/zuul.conf similarity index 100% rename from doc/source/admin/examples/etc_zuul/zuul.conf rename to doc/source/examples/etc_zuul/zuul.conf diff --git a/doc/source/admin/examples/httpd.conf b/doc/source/examples/httpd.conf similarity index 100% rename from doc/source/admin/examples/httpd.conf rename to doc/source/examples/httpd.conf diff --git a/doc/source/admin/examples/logs-Dockerfile b/doc/source/examples/logs-Dockerfile similarity index 100% rename from doc/source/admin/examples/logs-Dockerfile rename to doc/source/examples/logs-Dockerfile diff --git a/doc/source/admin/examples/node-Dockerfile b/doc/source/examples/node-Dockerfile similarity index 100% rename from doc/source/admin/examples/node-Dockerfile rename to doc/source/examples/node-Dockerfile diff --git a/doc/source/admin/examples/pipelines/gerrit-reference-pipelines.yaml b/doc/source/examples/pipelines/gerrit-reference-pipelines.yaml similarity index 100% rename from doc/source/admin/examples/pipelines/gerrit-reference-pipelines.yaml rename to doc/source/examples/pipelines/gerrit-reference-pipelines.yaml diff --git a/doc/source/admin/examples/pipelines/pagure-reference-pipelines.yaml b/doc/source/examples/pipelines/pagure-reference-pipelines.yaml similarity index 100% rename from doc/source/admin/examples/pipelines/pagure-reference-pipelines.yaml rename to doc/source/examples/pipelines/pagure-reference-pipelines.yaml diff --git a/doc/source/admin/examples/playbooks/project.config b/doc/source/examples/playbooks/project.config similarity index 100% rename from doc/source/admin/examples/playbooks/project.config rename to doc/source/examples/playbooks/project.config diff --git a/doc/source/admin/examples/playbooks/roles/create_project/tasks/main.yaml b/doc/source/examples/playbooks/roles/create_project/tasks/main.yaml similarity index 100% rename from doc/source/admin/examples/playbooks/roles/create_project/tasks/main.yaml rename to doc/source/examples/playbooks/roles/create_project/tasks/main.yaml diff --git a/doc/source/admin/examples/playbooks/setup.yaml b/doc/source/examples/playbooks/setup.yaml similarity index 100% rename from doc/source/admin/examples/playbooks/setup.yaml rename to doc/source/examples/playbooks/setup.yaml diff --git a/doc/source/admin/examples/playbooks/wait-to-start-gearman.sh b/doc/source/examples/playbooks/wait-to-start-gearman.sh similarity index 100% rename from doc/source/admin/examples/playbooks/wait-to-start-gearman.sh rename to doc/source/examples/playbooks/wait-to-start-gearman.sh diff --git a/doc/source/admin/examples/playbooks/wait-to-start.sh b/doc/source/examples/playbooks/wait-to-start.sh similarity index 100% rename from doc/source/admin/examples/playbooks/wait-to-start.sh rename to doc/source/examples/playbooks/wait-to-start.sh diff --git a/doc/source/admin/examples/test1/playbooks/testjob.yaml b/doc/source/examples/test1/playbooks/testjob.yaml similarity index 100% rename from doc/source/admin/examples/test1/playbooks/testjob.yaml rename to doc/source/examples/test1/playbooks/testjob.yaml diff --git a/doc/source/admin/examples/test1/zuul.yaml b/doc/source/examples/test1/zuul.yaml similarity index 100% rename from doc/source/admin/examples/test1/zuul.yaml rename to doc/source/examples/test1/zuul.yaml diff --git a/doc/source/admin/examples/zuul-config/playbooks/base/post-logs.yaml b/doc/source/examples/zuul-config/playbooks/base/post-logs.yaml similarity index 100% rename from doc/source/admin/examples/zuul-config/playbooks/base/post-logs.yaml rename to doc/source/examples/zuul-config/playbooks/base/post-logs.yaml diff --git a/doc/source/admin/examples/zuul-config/playbooks/base/post-ssh.yaml b/doc/source/examples/zuul-config/playbooks/base/post-ssh.yaml similarity index 100% rename from doc/source/admin/examples/zuul-config/playbooks/base/post-ssh.yaml rename to doc/source/examples/zuul-config/playbooks/base/post-ssh.yaml diff --git a/doc/source/admin/examples/zuul-config/playbooks/base/pre.yaml b/doc/source/examples/zuul-config/playbooks/base/pre.yaml similarity index 100% rename from doc/source/admin/examples/zuul-config/playbooks/base/pre.yaml rename to doc/source/examples/zuul-config/playbooks/base/pre.yaml diff --git a/doc/source/admin/examples/zuul-config/zuul.d/jobs.yaml b/doc/source/examples/zuul-config/zuul.d/jobs.yaml similarity index 100% rename from doc/source/admin/examples/zuul-config/zuul.d/jobs.yaml rename to doc/source/examples/zuul-config/zuul.d/jobs.yaml diff --git a/doc/source/admin/examples/zuul-config/zuul.d/jobs2.yaml b/doc/source/examples/zuul-config/zuul.d/jobs2.yaml similarity index 100% rename from doc/source/admin/examples/zuul-config/zuul.d/jobs2.yaml rename to doc/source/examples/zuul-config/zuul.d/jobs2.yaml diff --git a/doc/source/admin/examples/zuul-config/zuul.d/pipelines.yaml b/doc/source/examples/zuul-config/zuul.d/pipelines.yaml similarity index 100% rename from doc/source/admin/examples/zuul-config/zuul.d/pipelines.yaml rename to doc/source/examples/zuul-config/zuul.d/pipelines.yaml diff --git a/doc/source/admin/examples/zuul-config/zuul.d/projects.yaml b/doc/source/examples/zuul-config/zuul.d/projects.yaml similarity index 100% rename from doc/source/admin/examples/zuul-config/zuul.d/projects.yaml rename to doc/source/examples/zuul-config/zuul.d/projects.yaml diff --git a/doc/source/admin/centos7_setup.rst b/doc/source/howtos/admins/centos7_setup.rst similarity index 100% rename from doc/source/admin/centos7_setup.rst rename to doc/source/howtos/admins/centos7_setup.rst diff --git a/doc/source/admin/fedora27_setup.rst b/doc/source/howtos/admins/fedora27_setup.rst similarity index 100% rename from doc/source/admin/fedora27_setup.rst rename to doc/source/howtos/admins/fedora27_setup.rst diff --git a/doc/source/admin/gerrit_setup.rst b/doc/source/howtos/admins/gerrit_setup.rst similarity index 100% rename from doc/source/admin/gerrit_setup.rst rename to doc/source/howtos/admins/gerrit_setup.rst diff --git a/doc/source/admin/github_setup.rst b/doc/source/howtos/admins/github_setup.rst similarity index 100% rename from doc/source/admin/github_setup.rst rename to doc/source/howtos/admins/github_setup.rst diff --git a/doc/source/howtos/admins/index.rst b/doc/source/howtos/admins/index.rst new file mode 100644 index 0000000000..a829d25285 --- /dev/null +++ b/doc/source/howtos/admins/index.rst @@ -0,0 +1,9 @@ +Admin How-to Guides +=================== + +.. toctree:: + :maxdepth: 1 + + installation + zuul-from-scratch + troubleshooting diff --git a/doc/source/admin/installation.rst b/doc/source/howtos/admins/installation.rst similarity index 100% rename from doc/source/admin/installation.rst rename to doc/source/howtos/admins/installation.rst diff --git a/doc/source/admin/nodepool_install.rst b/doc/source/howtos/admins/nodepool_install.rst similarity index 100% rename from doc/source/admin/nodepool_install.rst rename to doc/source/howtos/admins/nodepool_install.rst diff --git a/doc/source/admin/nodepool_openstack.rst b/doc/source/howtos/admins/nodepool_openstack.rst similarity index 100% rename from doc/source/admin/nodepool_openstack.rst rename to doc/source/howtos/admins/nodepool_openstack.rst diff --git a/doc/source/admin/nodepool_static.rst b/doc/source/howtos/admins/nodepool_static.rst similarity index 100% rename from doc/source/admin/nodepool_static.rst rename to doc/source/howtos/admins/nodepool_static.rst diff --git a/doc/source/admin/opensuse_leap15_setup.rst b/doc/source/howtos/admins/opensuse_leap15_setup.rst similarity index 100% rename from doc/source/admin/opensuse_leap15_setup.rst rename to doc/source/howtos/admins/opensuse_leap15_setup.rst diff --git a/doc/source/admin/troubleshooting.rst b/doc/source/howtos/admins/troubleshooting.rst similarity index 100% rename from doc/source/admin/troubleshooting.rst rename to doc/source/howtos/admins/troubleshooting.rst diff --git a/doc/source/admin/zuul-from-scratch.rst b/doc/source/howtos/admins/zuul-from-scratch.rst similarity index 100% rename from doc/source/admin/zuul-from-scratch.rst rename to doc/source/howtos/admins/zuul-from-scratch.rst diff --git a/doc/source/admin/zuul_install.rst b/doc/source/howtos/admins/zuul_install.rst similarity index 100% rename from doc/source/admin/zuul_install.rst rename to doc/source/howtos/admins/zuul_install.rst diff --git a/doc/source/user/badges.rst b/doc/source/howtos/users/badges.rst similarity index 100% rename from doc/source/user/badges.rst rename to doc/source/howtos/users/badges.rst diff --git a/doc/source/user/howtos/cross-project-gating.rst b/doc/source/howtos/users/cross-project-gating.rst similarity index 100% rename from doc/source/user/howtos/cross-project-gating.rst rename to doc/source/howtos/users/cross-project-gating.rst diff --git a/doc/source/howtos/users/index.rst b/doc/source/howtos/users/index.rst new file mode 100644 index 0000000000..55f3d7cd95 --- /dev/null +++ b/doc/source/howtos/users/index.rst @@ -0,0 +1,9 @@ +User How-to Guides +================== + +.. toctree:: + :maxdepth: 1 + + cross-project-gating + pti + badges diff --git a/doc/source/user/howtos/pti.rst b/doc/source/howtos/users/pti.rst similarity index 100% rename from doc/source/user/howtos/pti.rst rename to doc/source/howtos/users/pti.rst diff --git a/doc/source/admin/images/become-select.png b/doc/source/images/become-select.png similarity index 100% rename from doc/source/admin/images/become-select.png rename to doc/source/images/become-select.png diff --git a/doc/source/admin/images/check1-1002.png b/doc/source/images/check1-1002.png similarity index 100% rename from doc/source/admin/images/check1-1002.png rename to doc/source/images/check1-1002.png diff --git a/doc/source/admin/images/check2-1002.png b/doc/source/images/check2-1002.png similarity index 100% rename from doc/source/admin/images/check2-1002.png rename to doc/source/images/check2-1002.png diff --git a/doc/source/admin/images/confirm.png b/doc/source/images/confirm.png similarity index 100% rename from doc/source/admin/images/confirm.png rename to doc/source/images/confirm.png diff --git a/doc/source/admin/images/email.png b/doc/source/images/email.png similarity index 100% rename from doc/source/admin/images/email.png rename to doc/source/images/email.png diff --git a/doc/source/admin/images/open-changes.png b/doc/source/images/open-changes.png similarity index 100% rename from doc/source/admin/images/open-changes.png rename to doc/source/images/open-changes.png diff --git a/doc/source/admin/images/orig/become-select.png b/doc/source/images/orig/become-select.png similarity index 100% rename from doc/source/admin/images/orig/become-select.png rename to doc/source/images/orig/become-select.png diff --git a/doc/source/admin/images/orig/check1-1002.png b/doc/source/images/orig/check1-1002.png similarity index 100% rename from doc/source/admin/images/orig/check1-1002.png rename to doc/source/images/orig/check1-1002.png diff --git a/doc/source/admin/images/orig/check2-1002.png b/doc/source/images/orig/check2-1002.png similarity index 100% rename from doc/source/admin/images/orig/check2-1002.png rename to doc/source/images/orig/check2-1002.png diff --git a/doc/source/admin/images/orig/confirm.png b/doc/source/images/orig/confirm.png similarity index 100% rename from doc/source/admin/images/orig/confirm.png rename to doc/source/images/orig/confirm.png diff --git a/doc/source/admin/images/orig/open-changes.png b/doc/source/images/orig/open-changes.png similarity index 100% rename from doc/source/admin/images/orig/open-changes.png rename to doc/source/images/orig/open-changes.png diff --git a/doc/source/admin/images/orig/recheck-1002.png b/doc/source/images/orig/recheck-1002.png similarity index 100% rename from doc/source/admin/images/orig/recheck-1002.png rename to doc/source/images/orig/recheck-1002.png diff --git a/doc/source/admin/images/orig/register.png b/doc/source/images/orig/register.png similarity index 100% rename from doc/source/admin/images/orig/register.png rename to doc/source/images/orig/register.png diff --git a/doc/source/admin/images/orig/review-1001.png b/doc/source/images/orig/review-1001.png similarity index 100% rename from doc/source/admin/images/orig/review-1001.png rename to doc/source/images/orig/review-1001.png diff --git a/doc/source/admin/images/orig/review-1003.png b/doc/source/images/orig/review-1003.png similarity index 100% rename from doc/source/admin/images/orig/review-1003.png rename to doc/source/images/orig/review-1003.png diff --git a/doc/source/admin/images/orig/settings.png b/doc/source/images/orig/settings.png similarity index 100% rename from doc/source/admin/images/orig/settings.png rename to doc/source/images/orig/settings.png diff --git a/doc/source/admin/images/orig/sign-in.png b/doc/source/images/orig/sign-in.png similarity index 100% rename from doc/source/admin/images/orig/sign-in.png rename to doc/source/images/orig/sign-in.png diff --git a/doc/source/admin/images/orig/sign-out-admin.png b/doc/source/images/orig/sign-out-admin.png similarity index 100% rename from doc/source/admin/images/orig/sign-out-admin.png rename to doc/source/images/orig/sign-out-admin.png diff --git a/doc/source/admin/images/orig/sign-out-user.png b/doc/source/images/orig/sign-out-user.png similarity index 100% rename from doc/source/admin/images/orig/sign-out-user.png rename to doc/source/images/orig/sign-out-user.png diff --git a/doc/source/admin/images/orig/submit-1001.png b/doc/source/images/orig/submit-1001.png similarity index 100% rename from doc/source/admin/images/orig/submit-1001.png rename to doc/source/images/orig/submit-1001.png diff --git a/doc/source/admin/images/profile.png b/doc/source/images/profile.png similarity index 100% rename from doc/source/admin/images/profile.png rename to doc/source/images/profile.png diff --git a/doc/source/admin/images/recheck-1002.png b/doc/source/images/recheck-1002.png similarity index 100% rename from doc/source/admin/images/recheck-1002.png rename to doc/source/images/recheck-1002.png diff --git a/doc/source/admin/images/register.png b/doc/source/images/register.png similarity index 100% rename from doc/source/admin/images/register.png rename to doc/source/images/register.png diff --git a/doc/source/admin/images/review-1001.png b/doc/source/images/review-1001.png similarity index 100% rename from doc/source/admin/images/review-1001.png rename to doc/source/images/review-1001.png diff --git a/doc/source/admin/images/review-1003.png b/doc/source/images/review-1003.png similarity index 100% rename from doc/source/admin/images/review-1003.png rename to doc/source/images/review-1003.png diff --git a/doc/source/admin/images/sign-in.png b/doc/source/images/sign-in.png similarity index 100% rename from doc/source/admin/images/sign-in.png rename to doc/source/images/sign-in.png diff --git a/doc/source/admin/images/sign-out-admin.png b/doc/source/images/sign-out-admin.png similarity index 100% rename from doc/source/admin/images/sign-out-admin.png rename to doc/source/images/sign-out-admin.png diff --git a/doc/source/admin/images/sign-out-user.png b/doc/source/images/sign-out-user.png similarity index 100% rename from doc/source/admin/images/sign-out-user.png rename to doc/source/images/sign-out-user.png diff --git a/doc/source/admin/images/sshkey.png b/doc/source/images/sshkey.png similarity index 100% rename from doc/source/admin/images/sshkey.png rename to doc/source/images/sshkey.png diff --git a/doc/source/admin/images/submit-1001.png b/doc/source/images/submit-1001.png similarity index 100% rename from doc/source/admin/images/submit-1001.png rename to doc/source/images/submit-1001.png diff --git a/doc/source/index.rst b/doc/source/index.rst index 7ff8f1006e..0139288b37 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -5,13 +5,6 @@ Zuul is a program that drives continuous integration, delivery, and deployment systems with a focus on project gating and interrelated projects. -Zuul's documentation is organized in three guides based on audience. -If Zuul is being used to gate or drive automation around your project, -read the :doc:`user/index` to find out how to configure Zuul. If you -are installing or operating a Zuul system, you will also find the -:doc:`admin/index` useful. If you want help make Zuul itself better, -take a look at the :doc:`developer/index`. - If you are looking for the Edge routing service named Zuul that is related to Netflix, it can be found here: https://github.com/Netflix/zuul @@ -20,30 +13,56 @@ If you are looking for the Javascript testing tool named Zuul, it can be found here: https://github.com/defunctzombie/zuul -Contents: +.. toctree:: + :maxdepth: 2 + + overview/index + +Documentation +------------- + +Zuul Users +********** .. toctree:: :maxdepth: 2 - user/index - admin/index - developer/index - releasenotes + tutorials/users/index .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - governance + howtos/users/index + +Zuul Admins +*********** .. toctree:: - :hidden: + :maxdepth: 2 - glossary + tutorials/admins/index + +.. toctree:: + :maxdepth: 2 + + howtos/admins/index + +Digging Deeper +************** + +.. toctree:: + :maxdepth: 2 + + discussions/index + +.. toctree:: + :maxdepth: 2 + + references/index Indices and tables -================== +------------------ * :ref:`genindex` * :ref:`search` -* :ref:`glossary` diff --git a/doc/source/governance.rst b/doc/source/overview/governance.rst similarity index 100% rename from doc/source/governance.rst rename to doc/source/overview/governance.rst diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst new file mode 100644 index 0000000000..cef4efb3bc --- /dev/null +++ b/doc/source/overview/index.rst @@ -0,0 +1,9 @@ +Overview +======== + +.. toctree:: + :maxdepth: 2 + + governance + vulnerabilities + releasenotes diff --git a/doc/source/releasenotes.rst b/doc/source/overview/releasenotes.rst similarity index 86% rename from doc/source/releasenotes.rst rename to doc/source/overview/releasenotes.rst index 01f163dd32..0b2e15be9f 100644 --- a/doc/source/releasenotes.rst +++ b/doc/source/overview/releasenotes.rst @@ -1,4 +1,3 @@ -============= Release Notes ============= diff --git a/doc/source/user/vulnerabilities.rst b/doc/source/overview/vulnerabilities.rst similarity index 100% rename from doc/source/user/vulnerabilities.rst rename to doc/source/overview/vulnerabilities.rst diff --git a/doc/source/admin/client.rst b/doc/source/references/client.rst similarity index 100% rename from doc/source/admin/client.rst rename to doc/source/references/client.rst diff --git a/doc/source/user/config.rst b/doc/source/references/config.rst similarity index 99% rename from doc/source/user/config.rst rename to doc/source/references/config.rst index d3cc83fd36..04583feacd 100644 --- a/doc/source/user/config.rst +++ b/doc/source/references/config.rst @@ -184,7 +184,7 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of appear in the repository when merged. For more detail on the theory and operation of Zuul's - dependent pipeline manager, see: :doc:`gating`. + dependent pipeline manager, see: :doc:`/discussions/gating`. .. value:: supercedent diff --git a/doc/source/admin/connections.rst b/doc/source/references/connections.rst similarity index 100% rename from doc/source/admin/connections.rst rename to doc/source/references/connections.rst diff --git a/doc/source/developer/ansible.rst b/doc/source/references/developer/ansible.rst similarity index 100% rename from doc/source/developer/ansible.rst rename to doc/source/references/developer/ansible.rst diff --git a/doc/source/developer/datamodel.rst b/doc/source/references/developer/datamodel.rst similarity index 100% rename from doc/source/developer/datamodel.rst rename to doc/source/references/developer/datamodel.rst diff --git a/doc/source/developer/docs.rst b/doc/source/references/developer/docs.rst similarity index 100% rename from doc/source/developer/docs.rst rename to doc/source/references/developer/docs.rst diff --git a/doc/source/developer/drivers.rst b/doc/source/references/developer/drivers.rst similarity index 100% rename from doc/source/developer/drivers.rst rename to doc/source/references/developer/drivers.rst diff --git a/doc/source/developer/index.rst b/doc/source/references/developer/index.rst similarity index 100% rename from doc/source/developer/index.rst rename to doc/source/references/developer/index.rst diff --git a/doc/source/developer/javascript.rst b/doc/source/references/developer/javascript.rst similarity index 100% rename from doc/source/developer/javascript.rst rename to doc/source/references/developer/javascript.rst diff --git a/doc/source/developer/releasenotes.rst b/doc/source/references/developer/releasenotes.rst similarity index 100% rename from doc/source/developer/releasenotes.rst rename to doc/source/references/developer/releasenotes.rst diff --git a/doc/source/developer/specs/container-build-resources.rst b/doc/source/references/developer/specs/container-build-resources.rst similarity index 100% rename from doc/source/developer/specs/container-build-resources.rst rename to doc/source/references/developer/specs/container-build-resources.rst diff --git a/doc/source/developer/specs/index.rst b/doc/source/references/developer/specs/index.rst similarity index 100% rename from doc/source/developer/specs/index.rst rename to doc/source/references/developer/specs/index.rst diff --git a/doc/source/developer/specs/kubernetes-operator.rst b/doc/source/references/developer/specs/kubernetes-operator.rst similarity index 100% rename from doc/source/developer/specs/kubernetes-operator.rst rename to doc/source/references/developer/specs/kubernetes-operator.rst diff --git a/doc/source/developer/specs/logs.rst b/doc/source/references/developer/specs/logs.rst similarity index 100% rename from doc/source/developer/specs/logs.rst rename to doc/source/references/developer/specs/logs.rst diff --git a/doc/source/developer/specs/multiple-ansible-versions.rst b/doc/source/references/developer/specs/multiple-ansible-versions.rst similarity index 100% rename from doc/source/developer/specs/multiple-ansible-versions.rst rename to doc/source/references/developer/specs/multiple-ansible-versions.rst diff --git a/doc/source/developer/specs/tenant-scoped-admin-web-API.rst b/doc/source/references/developer/specs/tenant-scoped-admin-web-API.rst similarity index 100% rename from doc/source/developer/specs/tenant-scoped-admin-web-API.rst rename to doc/source/references/developer/specs/tenant-scoped-admin-web-API.rst diff --git a/doc/source/developer/testing.rst b/doc/source/references/developer/testing.rst similarity index 100% rename from doc/source/developer/testing.rst rename to doc/source/references/developer/testing.rst diff --git a/doc/source/developer/triggers.rst b/doc/source/references/developer/triggers.rst similarity index 100% rename from doc/source/developer/triggers.rst rename to doc/source/references/developer/triggers.rst diff --git a/doc/source/admin/drivers/gerrit.rst b/doc/source/references/drivers/gerrit.rst similarity index 99% rename from doc/source/admin/drivers/gerrit.rst rename to doc/source/references/drivers/gerrit.rst index ad06cfa2ae..61b45877e9 100644 --- a/doc/source/admin/drivers/gerrit.rst +++ b/doc/source/references/drivers/gerrit.rst @@ -357,7 +357,7 @@ Reference Pipelines Configuration Here is an example of standard pipelines you may want to define: -.. literalinclude:: ../examples/pipelines/gerrit-reference-pipelines.yaml +.. literalinclude:: /examples/pipelines/gerrit-reference-pipelines.yaml :language: yaml Checks Plugin Support (Experimental) diff --git a/doc/source/admin/drivers/git.rst b/doc/source/references/drivers/git.rst similarity index 100% rename from doc/source/admin/drivers/git.rst rename to doc/source/references/drivers/git.rst diff --git a/doc/source/admin/drivers/github.rst b/doc/source/references/drivers/github.rst similarity index 100% rename from doc/source/admin/drivers/github.rst rename to doc/source/references/drivers/github.rst diff --git a/doc/source/admin/drivers/mqtt.rst b/doc/source/references/drivers/mqtt.rst similarity index 100% rename from doc/source/admin/drivers/mqtt.rst rename to doc/source/references/drivers/mqtt.rst diff --git a/doc/source/admin/drivers/pagure.rst b/doc/source/references/drivers/pagure.rst similarity index 99% rename from doc/source/admin/drivers/pagure.rst rename to doc/source/references/drivers/pagure.rst index 84eec5dce1..320cf33f8d 100644 --- a/doc/source/admin/drivers/pagure.rst +++ b/doc/source/references/drivers/pagure.rst @@ -252,5 +252,5 @@ Reference pipelines configuration Here is an example of standard pipelines you may want to define: -.. literalinclude:: ../examples/pipelines/pagure-reference-pipelines.yaml +.. literalinclude:: /examples/pipelines/pagure-reference-pipelines.yaml :language: yaml diff --git a/doc/source/admin/drivers/smtp.rst b/doc/source/references/drivers/smtp.rst similarity index 100% rename from doc/source/admin/drivers/smtp.rst rename to doc/source/references/drivers/smtp.rst diff --git a/doc/source/admin/drivers/sql.rst b/doc/source/references/drivers/sql.rst similarity index 100% rename from doc/source/admin/drivers/sql.rst rename to doc/source/references/drivers/sql.rst diff --git a/doc/source/admin/drivers/timer.rst b/doc/source/references/drivers/timer.rst similarity index 100% rename from doc/source/admin/drivers/timer.rst rename to doc/source/references/drivers/timer.rst diff --git a/doc/source/admin/drivers/zuul.rst b/doc/source/references/drivers/zuul.rst similarity index 100% rename from doc/source/admin/drivers/zuul.rst rename to doc/source/references/drivers/zuul.rst diff --git a/doc/source/glossary.rst b/doc/source/references/glossary.rst similarity index 100% rename from doc/source/glossary.rst rename to doc/source/references/glossary.rst diff --git a/doc/source/references/index.rst b/doc/source/references/index.rst new file mode 100644 index 0000000000..eb23ebf9bb --- /dev/null +++ b/doc/source/references/index.rst @@ -0,0 +1,14 @@ +References +========== + +.. toctree:: + :maxdepth: 2 + + developer/index + jobs + config + connections + client + monitoring + web + glossary diff --git a/doc/source/user/jobs.rst b/doc/source/references/jobs.rst similarity index 100% rename from doc/source/user/jobs.rst rename to doc/source/references/jobs.rst diff --git a/doc/source/admin/monitoring.rst b/doc/source/references/monitoring.rst similarity index 100% rename from doc/source/admin/monitoring.rst rename to doc/source/references/monitoring.rst diff --git a/doc/source/user/web.rst b/doc/source/references/web.rst similarity index 100% rename from doc/source/user/web.rst rename to doc/source/references/web.rst diff --git a/doc/source/tutorials/admins/index.rst b/doc/source/tutorials/admins/index.rst new file mode 100644 index 0000000000..826d56062c --- /dev/null +++ b/doc/source/tutorials/admins/index.rst @@ -0,0 +1,7 @@ +Admin Tutorials +=============== + +.. toctree:: + :maxdepth: 1 + + quick-start diff --git a/doc/source/admin/quick-start.rst b/doc/source/tutorials/admins/quick-start.rst similarity index 93% rename from doc/source/admin/quick-start.rst rename to doc/source/tutorials/admins/quick-start.rst index 2918d62b80..5b028c9a8e 100644 --- a/doc/source/admin/quick-start.rst +++ b/doc/source/tutorials/admins/quick-start.rst @@ -71,11 +71,11 @@ docker-compose in order to start Zuul, Nodepool and Gerrit. .. code-block:: shell - cd zuul/doc/source/admin/examples + cd zuul/doc/source/examples sudo -E docker-compose up For reference, the files in that directory are also `browsable on the web -`_. +`_. All of the services will be started with debug-level logging sent to the standard output of the terminal where docker-compose is running. @@ -127,25 +127,25 @@ system at any time. To create your Gerrit account, visit http://localhost:8080 in your browser and click `Sign in` in the top right corner. -.. image:: images/sign-in.png +.. image:: /images/sign-in.png :align: center Then click `New Account` under `Register`. -.. image:: images/register.png +.. image:: /images/register.png :align: center Don't bother to enter anything into the confirmation dialog that pops up, instead, click the `settings` link at the bottom. -.. image:: images/confirm.png +.. image:: /images/confirm.png :align: center In the `Profile` section at the top, enter the username you use to log into your workstation in the `Username` field and your full name in the `Full name` field, then click `Save Changes`. -.. image:: images/profile.png +.. image:: /images/profile.png :align: center Scroll down to the `Email Addresses` section and enter your email @@ -155,14 +155,14 @@ actually send any email, and the address will be automatically confirmed. This step is useful since several parts of the Gerrit user interface expect to be able to display email addresses. -.. image:: images/email.png +.. image:: /images/email.png :align: center Scroll down to the `SSH keys` section and copy and paste the contents of ``~/.ssh/id_rsa.pub`` into the `New SSH key` field and click `Add New SSH Key`. -.. image:: images/sshkey.png +.. image:: /images/sshkey.png :align: center .. We ask them to click reload so that the page refreshes and their @@ -227,7 +227,7 @@ uploaded) and if these final tests pass, will automatically merge the change. To configure these pipelines, copy the following file into `zuul.d/pipelines.yaml`: -.. literalinclude:: examples/zuul-config/zuul.d/pipelines.yaml +.. literalinclude:: /examples/zuul-config/zuul.d/pipelines.yaml :language: yaml Once we have bootstrapped our initial Zuul configuration, we will want @@ -245,7 +245,7 @@ pipelines for ``zuul-config`` to run the ``noop`` job, and add all projects to those pipelines (with no jobs), copy the following file into ``zuul.d/projects.yaml``: -.. literalinclude:: examples/zuul-config/zuul.d/projects.yaml +.. literalinclude:: /examples/zuul-config/zuul.d/projects.yaml :language: yaml Every real job (i.e., all jobs other than ``noop``) must inherit from a @@ -253,7 +253,7 @@ Every real job (i.e., all jobs other than ``noop``) must inherit from a :term:`config-project`. Let's go ahead and add a simple base job that we can build on later. Copy the following into ``zuul.d/jobs.yaml``: -.. literalinclude:: examples/zuul-config/zuul.d/jobs.yaml +.. literalinclude:: /examples/zuul-config/zuul.d/jobs.yaml :language: yaml Commit the changes and push them up for review: @@ -273,23 +273,23 @@ then: Click the avatar image in the top right corner then click `Sign out`. -.. image:: images/sign-out-user.png +.. image:: /images/sign-out-user.png :align: center Then click the `Sign in` link again. -.. image:: images/sign-in.png +.. image:: /images/sign-in.png :align: center Click `admin` to log in as the `admin` user. -.. image:: images/become-select.png +.. image:: /images/become-select.png :align: center You will then see a list of open changes; click on the change you uploaded. -.. image:: images/open-changes.png +.. image:: /images/open-changes.png :align: center Click `Reply...` at the top center of the change screen. This will @@ -299,7 +299,7 @@ review categories, even `Verified` which is normally reserved for Zuul. Vote Code-Review: +2, Verified: +2, Workflow: +1, and then click `Send` to leave your approval votes. -.. image:: images/review-1001.png +.. image:: /images/review-1001.png :align: center Once the required votes have been set, the `Submit` button will appear @@ -307,7 +307,7 @@ in the top right; click it. This will cause the change to be merged immediately. This is normally handled by Zuul, but as the administrator you can bypass Zuul to forcibly merge a change. -.. image:: images/submit-1001.png +.. image:: /images/submit-1001.png :align: center Now that the initial configuration has been bootstrapped, you should @@ -315,17 +315,17 @@ not need to bypass testing and code review again, so switch back to the account you created for yourself. Click on the avatar image in the top right corner then click `Sign out`. -.. image:: images/sign-out-admin.png +.. image:: /images/sign-out-admin.png :align: center Then click the `Sign in` link again. -.. image:: images/sign-in.png +.. image:: /images/sign-in.png :align: center And click your username to log into your account. -.. image:: images/become-select.png +.. image:: /images/become-select.png :align: center Test Zuul Pipelines @@ -358,7 +358,7 @@ sub-directory in the project to hold playbooks: Start with a simple playbook which just outputs a debug message. Copy the following to ``playbooks/testjob.yaml``: -.. literalinclude:: examples/test1/playbooks/testjob.yaml +.. literalinclude:: /examples/test1/playbooks/testjob.yaml :language: yaml Now define a Zuul job which runs that playbook. Zuul will read its @@ -368,7 +368,7 @@ project* which isn't dedicated entirely to Zuul, it's best to put Zuul's configuration in a hidden file. Copy the following to ``.zuul.yaml`` in the root of the project: -.. literalinclude:: examples/test1/zuul.yaml +.. literalinclude:: /examples/test1/zuul.yaml :language: yaml Commit the changes and push them up to Gerrit for review: @@ -391,7 +391,7 @@ there are no logs and no way to see the output, only a `finger` URL (which is what Zuul reports when it doesn't know where build logs are stored). -.. image:: images/check1-1002.png +.. image:: /images/check1-1002.png :align: center This means everything is working so far, but we need to configure a @@ -431,7 +431,7 @@ Zuul supports running any number of playbooks before a job (called We're going to add a single *pre-run* playbook now. Copy the following to ``playbooks/base/pre.yaml``: -.. literalinclude:: examples/zuul-config/playbooks/base/pre.yaml +.. literalinclude:: /examples/zuul-config/playbooks/base/pre.yaml :language: yaml This playbook does two things; first it creates a new SSH key and adds @@ -446,7 +446,7 @@ changes being tested) to all of the nodes used in the job. Next, add a *post-run* playbook to remove the per-build SSH key. Copy the following to ``playbooks/base/post-ssh.yaml``: -.. literalinclude:: examples/zuul-config/playbooks/base/post-ssh.yaml +.. literalinclude:: /examples/zuul-config/playbooks/base/post-ssh.yaml :language: yaml This is the complement of the `add-build-sshkey` role in the pre-run @@ -457,7 +457,7 @@ always want log collection to run and we want it to run last, we create a second post-run playbook for it. Copy the following to ``playbooks/base/post-logs.yaml``: -.. literalinclude:: examples/zuul-config/playbooks/base/post-logs.yaml +.. literalinclude:: /examples/zuul-config/playbooks/base/post-logs.yaml :language: yaml This tutorial is running an Apache webserver in a container which will @@ -481,7 +481,7 @@ Now that the new playbooks are in place, update the ``base`` job definition to include them. Overwrite ``zuul.d/jobs.yaml`` with the following: -.. literalinclude:: examples/zuul-config/zuul.d/jobs2.yaml +.. literalinclude:: /examples/zuul-config/zuul.d/jobs2.yaml :language: yaml Then commit the change and upload it to Gerrit for review: @@ -498,7 +498,7 @@ Visit http://localhost:8080/dashboard/self and open the You should see a Verified +1 vote from Zuul. Click `Reply` then vote Code-Review: +2 and Workflow: +1 then click `Send`. -.. image:: images/review-1003.png +.. image:: /images/review-1003.png :align: center Wait a few moments for Zuul to process the event, and then reload the @@ -508,7 +508,7 @@ Visit http://localhost:8080/dashboard/self and return to the ``test1`` change you uploaded earlier. Click `Reply` then type `recheck` into the text field and click `Send`. -.. image:: images/recheck-1002.png +.. image:: /images/recheck-1002.png :align: center This will cause Zuul to re-run the test job we created earlier. This @@ -516,7 +516,7 @@ time it will run with the updated base job configuration, and when complete, it will report the published log location as a comment on the change: -.. image:: images/check2-1002.png +.. image:: /images/check2-1002.png :align: center Follow the link and you will be able to browse the console log for the @@ -527,7 +527,7 @@ Further Steps ------------- If you would like to make further changes to Zuul, its configuration -files are located in the ``zuul/doc/source/admin/examples`` directory +files are located in the ``zuul/doc/source/examples`` directory and are bind-mounted into the running containers. You may edit them and restart the Zuul containers to make changes. diff --git a/doc/source/tutorials/users/index.rst b/doc/source/tutorials/users/index.rst new file mode 100644 index 0000000000..1f65bad432 --- /dev/null +++ b/doc/source/tutorials/users/index.rst @@ -0,0 +1,5 @@ +User Tutorials +============== + +.. toctree:: + :maxdepth: 1 diff --git a/doc/source/user/client-user.rst b/doc/source/user/client-user.rst deleted file mode 100644 index 3886cd45e0..0000000000 --- a/doc/source/user/client-user.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../admin/client.rst diff --git a/doc/source/user/howtos.rst b/doc/source/user/howtos.rst deleted file mode 100644 index c1f4f3fdb0..0000000000 --- a/doc/source/user/howtos.rst +++ /dev/null @@ -1,12 +0,0 @@ -:title: HowTos - -.. _howtos: - -HowTos: Recommended Practices -============================= - -.. toctree:: - :maxdepth: 2 - - howtos/pti - howtos/cross-project-gating diff --git a/playbooks/quick-start/main.yaml b/playbooks/quick-start/main.yaml index 48531fe535..5487fc68f4 100644 --- a/playbooks/quick-start/main.yaml +++ b/playbooks/quick-start/main.yaml @@ -2,7 +2,7 @@ when: not local shell: cmd: docker-compose up -d - chdir: src/opendev.org/zuul/zuul/doc/source/admin/examples + chdir: src/opendev.org/zuul/zuul/doc/source/examples - name: Run docker-compose up when: local shell: @@ -63,7 +63,7 @@ dest: "{{ workspace }}/zuul-config" - name: Make initial change in zuul-config copy: - src: ../../doc/source/admin/examples/zuul-config/ + src: ../../doc/source/examples/zuul-config/ dest: "{{ workspace }}/zuul-config/" - name: Commit and upload initial change in zuul-config shell: @@ -129,7 +129,7 @@ dest: "{{ workspace }}/test1" - name: Make test change in test1 copy: - src: ../../doc/source/admin/examples/test1/ + src: ../../doc/source/examples/test1/ dest: "{{ workspace }}/test1/" - name: Commit and upload test change in test1 shell: