Browse Source

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
tags/3.15.0
David Shrewsbury 2 weeks ago
parent
commit
e6d8b210cc
100 changed files with 70 additions and 52 deletions
  1. +0
    -23
      doc/source/admin/index.rst
  2. +0
    -0
      doc/source/discussions/components.rst
  3. +0
    -0
      doc/source/discussions/concepts.rst
  4. +0
    -0
      doc/source/discussions/encryption.rst
  5. +0
    -0
      doc/source/discussions/gating.rst
  6. +5
    -9
      doc/source/discussions/index.rst
  7. +0
    -0
      doc/source/discussions/tenant-scoped-rest-api.rst
  8. +0
    -0
      doc/source/discussions/tenants.rst
  9. +0
    -0
      doc/source/examples/docker-compose.yaml
  10. +0
    -0
      doc/source/examples/etc_nodepool/nodepool.yaml
  11. +0
    -0
      doc/source/examples/etc_zuul/main.yaml
  12. +0
    -0
      doc/source/examples/etc_zuul/zuul.conf
  13. +0
    -0
      doc/source/examples/httpd.conf
  14. +0
    -0
      doc/source/examples/logs-Dockerfile
  15. +0
    -0
      doc/source/examples/node-Dockerfile
  16. +0
    -0
      doc/source/examples/pipelines/gerrit-reference-pipelines.yaml
  17. +0
    -0
      doc/source/examples/pipelines/pagure-reference-pipelines.yaml
  18. +0
    -0
      doc/source/examples/playbooks/project.config
  19. +0
    -0
      doc/source/examples/playbooks/roles/create_project/tasks/main.yaml
  20. +0
    -0
      doc/source/examples/playbooks/setup.yaml
  21. +0
    -0
      doc/source/examples/playbooks/wait-to-start-gearman.sh
  22. +0
    -0
      doc/source/examples/playbooks/wait-to-start.sh
  23. +0
    -0
      doc/source/examples/test1/playbooks/testjob.yaml
  24. +0
    -0
      doc/source/examples/test1/zuul.yaml
  25. +0
    -0
      doc/source/examples/zuul-config/playbooks/base/post-logs.yaml
  26. +0
    -0
      doc/source/examples/zuul-config/playbooks/base/post-ssh.yaml
  27. +0
    -0
      doc/source/examples/zuul-config/playbooks/base/pre.yaml
  28. +0
    -0
      doc/source/examples/zuul-config/zuul.d/jobs.yaml
  29. +0
    -0
      doc/source/examples/zuul-config/zuul.d/jobs2.yaml
  30. +0
    -0
      doc/source/examples/zuul-config/zuul.d/pipelines.yaml
  31. +0
    -0
      doc/source/examples/zuul-config/zuul.d/projects.yaml
  32. +0
    -0
      doc/source/howtos/admins/centos7_setup.rst
  33. +0
    -0
      doc/source/howtos/admins/fedora27_setup.rst
  34. +0
    -0
      doc/source/howtos/admins/gerrit_setup.rst
  35. +0
    -0
      doc/source/howtos/admins/github_setup.rst
  36. +9
    -0
      doc/source/howtos/admins/index.rst
  37. +0
    -0
      doc/source/howtos/admins/installation.rst
  38. +0
    -0
      doc/source/howtos/admins/nodepool_install.rst
  39. +0
    -0
      doc/source/howtos/admins/nodepool_openstack.rst
  40. +0
    -0
      doc/source/howtos/admins/nodepool_static.rst
  41. +0
    -0
      doc/source/howtos/admins/opensuse_leap15_setup.rst
  42. +0
    -0
      doc/source/howtos/admins/troubleshooting.rst
  43. +0
    -0
      doc/source/howtos/admins/zuul-from-scratch.rst
  44. +0
    -0
      doc/source/howtos/admins/zuul_install.rst
  45. +0
    -0
      doc/source/howtos/users/badges.rst
  46. +0
    -0
      doc/source/howtos/users/cross-project-gating.rst
  47. +9
    -0
      doc/source/howtos/users/index.rst
  48. +0
    -0
      doc/source/howtos/users/pti.rst
  49. +0
    -0
      doc/source/images/become-select.png
  50. +0
    -0
      doc/source/images/check1-1002.png
  51. +0
    -0
      doc/source/images/check2-1002.png
  52. +0
    -0
      doc/source/images/confirm.png
  53. +0
    -0
      doc/source/images/email.png
  54. +0
    -0
      doc/source/images/open-changes.png
  55. +0
    -0
      doc/source/images/orig/become-select.png
  56. +0
    -0
      doc/source/images/orig/check1-1002.png
  57. +0
    -0
      doc/source/images/orig/check2-1002.png
  58. +0
    -0
      doc/source/images/orig/confirm.png
  59. +0
    -0
      doc/source/images/orig/open-changes.png
  60. +0
    -0
      doc/source/images/orig/recheck-1002.png
  61. +0
    -0
      doc/source/images/orig/register.png
  62. +0
    -0
      doc/source/images/orig/review-1001.png
  63. +0
    -0
      doc/source/images/orig/review-1003.png
  64. +0
    -0
      doc/source/images/orig/settings.png
  65. +0
    -0
      doc/source/images/orig/sign-in.png
  66. +0
    -0
      doc/source/images/orig/sign-out-admin.png
  67. +0
    -0
      doc/source/images/orig/sign-out-user.png
  68. +0
    -0
      doc/source/images/orig/submit-1001.png
  69. +0
    -0
      doc/source/images/profile.png
  70. +0
    -0
      doc/source/images/recheck-1002.png
  71. +0
    -0
      doc/source/images/register.png
  72. +0
    -0
      doc/source/images/review-1001.png
  73. +0
    -0
      doc/source/images/review-1003.png
  74. +0
    -0
      doc/source/images/sign-in.png
  75. +0
    -0
      doc/source/images/sign-out-admin.png
  76. +0
    -0
      doc/source/images/sign-out-user.png
  77. +0
    -0
      doc/source/images/sshkey.png
  78. +0
    -0
      doc/source/images/submit-1001.png
  79. +37
    -18
      doc/source/index.rst
  80. +0
    -0
      doc/source/overview/governance.rst
  81. +9
    -0
      doc/source/overview/index.rst
  82. +0
    -1
      doc/source/overview/releasenotes.rst
  83. +0
    -0
      doc/source/overview/vulnerabilities.rst
  84. +0
    -0
      doc/source/references/client.rst
  85. +1
    -1
      doc/source/references/config.rst
  86. +0
    -0
      doc/source/references/connections.rst
  87. +0
    -0
      doc/source/references/developer/ansible.rst
  88. +0
    -0
      doc/source/references/developer/datamodel.rst
  89. +0
    -0
      doc/source/references/developer/docs.rst
  90. +0
    -0
      doc/source/references/developer/drivers.rst
  91. +0
    -0
      doc/source/references/developer/index.rst
  92. +0
    -0
      doc/source/references/developer/javascript.rst
  93. +0
    -0
      doc/source/references/developer/releasenotes.rst
  94. +0
    -0
      doc/source/references/developer/specs/container-build-resources.rst
  95. +0
    -0
      doc/source/references/developer/specs/index.rst
  96. +0
    -0
      doc/source/references/developer/specs/kubernetes-operator.rst
  97. +0
    -0
      doc/source/references/developer/specs/logs.rst
  98. +0
    -0
      doc/source/references/developer/specs/multiple-ansible-versions.rst
  99. +0
    -0
      doc/source/references/developer/specs/tenant-scoped-admin-web-API.rst
  100. +0
    -0
      doc/source/references/developer/testing.rst

+ 0
- 23
doc/source/admin/index.rst View File

@@ -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

doc/source/admin/components.rst → doc/source/discussions/components.rst View File


doc/source/user/concepts.rst → doc/source/discussions/concepts.rst View File


doc/source/user/encryption.rst → doc/source/discussions/encryption.rst View File


doc/source/user/gating.rst → doc/source/discussions/gating.rst View File


doc/source/user/index.rst → doc/source/discussions/index.rst View File

@@ -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

doc/source/admin/tenant-scoped-rest-api.rst → doc/source/discussions/tenant-scoped-rest-api.rst View File


doc/source/admin/tenants.rst → doc/source/discussions/tenants.rst View File


doc/source/admin/examples/docker-compose.yaml → doc/source/examples/docker-compose.yaml View File


doc/source/admin/examples/etc_nodepool/nodepool.yaml → doc/source/examples/etc_nodepool/nodepool.yaml View File


doc/source/admin/examples/etc_zuul/main.yaml → doc/source/examples/etc_zuul/main.yaml View File


doc/source/admin/examples/etc_zuul/zuul.conf → doc/source/examples/etc_zuul/zuul.conf View File


doc/source/admin/examples/httpd.conf → doc/source/examples/httpd.conf View File


doc/source/admin/examples/logs-Dockerfile → doc/source/examples/logs-Dockerfile View File


doc/source/admin/examples/node-Dockerfile → doc/source/examples/node-Dockerfile View File


doc/source/admin/examples/pipelines/gerrit-reference-pipelines.yaml → doc/source/examples/pipelines/gerrit-reference-pipelines.yaml View File


doc/source/admin/examples/pipelines/pagure-reference-pipelines.yaml → doc/source/examples/pipelines/pagure-reference-pipelines.yaml View File


doc/source/admin/examples/playbooks/project.config → doc/source/examples/playbooks/project.config View File


doc/source/admin/examples/playbooks/roles/create_project/tasks/main.yaml → doc/source/examples/playbooks/roles/create_project/tasks/main.yaml View File


doc/source/admin/examples/playbooks/setup.yaml → doc/source/examples/playbooks/setup.yaml View File


doc/source/admin/examples/playbooks/wait-to-start-gearman.sh → doc/source/examples/playbooks/wait-to-start-gearman.sh View File


doc/source/admin/examples/playbooks/wait-to-start.sh → doc/source/examples/playbooks/wait-to-start.sh View File


doc/source/admin/examples/test1/playbooks/testjob.yaml → doc/source/examples/test1/playbooks/testjob.yaml View File


doc/source/admin/examples/test1/zuul.yaml → doc/source/examples/test1/zuul.yaml View File


doc/source/admin/examples/zuul-config/playbooks/base/post-logs.yaml → doc/source/examples/zuul-config/playbooks/base/post-logs.yaml View File


doc/source/admin/examples/zuul-config/playbooks/base/post-ssh.yaml → doc/source/examples/zuul-config/playbooks/base/post-ssh.yaml View File


doc/source/admin/examples/zuul-config/playbooks/base/pre.yaml → doc/source/examples/zuul-config/playbooks/base/pre.yaml View File


doc/source/admin/examples/zuul-config/zuul.d/jobs.yaml → doc/source/examples/zuul-config/zuul.d/jobs.yaml View File


doc/source/admin/examples/zuul-config/zuul.d/jobs2.yaml → doc/source/examples/zuul-config/zuul.d/jobs2.yaml View File


doc/source/admin/examples/zuul-config/zuul.d/pipelines.yaml → doc/source/examples/zuul-config/zuul.d/pipelines.yaml View File


doc/source/admin/examples/zuul-config/zuul.d/projects.yaml → doc/source/examples/zuul-config/zuul.d/projects.yaml View File


doc/source/admin/centos7_setup.rst → doc/source/howtos/admins/centos7_setup.rst View File


doc/source/admin/fedora27_setup.rst → doc/source/howtos/admins/fedora27_setup.rst View File


doc/source/admin/gerrit_setup.rst → doc/source/howtos/admins/gerrit_setup.rst View File


doc/source/admin/github_setup.rst → doc/source/howtos/admins/github_setup.rst View File


+ 9
- 0
doc/source/howtos/admins/index.rst View File

@@ -0,0 +1,9 @@
Admin How-to Guides
===================

.. toctree::
:maxdepth: 1

installation
zuul-from-scratch
troubleshooting

doc/source/admin/installation.rst → doc/source/howtos/admins/installation.rst View File


doc/source/admin/nodepool_install.rst → doc/source/howtos/admins/nodepool_install.rst View File


doc/source/admin/nodepool_openstack.rst → doc/source/howtos/admins/nodepool_openstack.rst View File


doc/source/admin/nodepool_static.rst → doc/source/howtos/admins/nodepool_static.rst View File


doc/source/admin/opensuse_leap15_setup.rst → doc/source/howtos/admins/opensuse_leap15_setup.rst View File


doc/source/admin/troubleshooting.rst → doc/source/howtos/admins/troubleshooting.rst View File


doc/source/admin/zuul-from-scratch.rst → doc/source/howtos/admins/zuul-from-scratch.rst View File


doc/source/admin/zuul_install.rst → doc/source/howtos/admins/zuul_install.rst View File


doc/source/user/badges.rst → doc/source/howtos/users/badges.rst View File


doc/source/user/howtos/cross-project-gating.rst → doc/source/howtos/users/cross-project-gating.rst View File


+ 9
- 0
doc/source/howtos/users/index.rst View File

@@ -0,0 +1,9 @@
User How-to Guides
==================

.. toctree::
:maxdepth: 1

cross-project-gating
pti
badges

doc/source/user/howtos/pti.rst → doc/source/howtos/users/pti.rst View File


doc/source/admin/images/become-select.png → doc/source/images/become-select.png View File


doc/source/admin/images/check1-1002.png → doc/source/images/check1-1002.png View File


doc/source/admin/images/check2-1002.png → doc/source/images/check2-1002.png View File


doc/source/admin/images/confirm.png → doc/source/images/confirm.png View File


doc/source/admin/images/email.png → doc/source/images/email.png View File


doc/source/admin/images/open-changes.png → doc/source/images/open-changes.png View File


doc/source/admin/images/orig/become-select.png → doc/source/images/orig/become-select.png View File


doc/source/admin/images/orig/check1-1002.png → doc/source/images/orig/check1-1002.png View File


doc/source/admin/images/orig/check2-1002.png → doc/source/images/orig/check2-1002.png View File


doc/source/admin/images/orig/confirm.png → doc/source/images/orig/confirm.png View File


doc/source/admin/images/orig/open-changes.png → doc/source/images/orig/open-changes.png View File


doc/source/admin/images/orig/recheck-1002.png → doc/source/images/orig/recheck-1002.png View File


doc/source/admin/images/orig/register.png → doc/source/images/orig/register.png View File


doc/source/admin/images/orig/review-1001.png → doc/source/images/orig/review-1001.png View File


doc/source/admin/images/orig/review-1003.png → doc/source/images/orig/review-1003.png View File


doc/source/admin/images/orig/settings.png → doc/source/images/orig/settings.png View File


doc/source/admin/images/orig/sign-in.png → doc/source/images/orig/sign-in.png View File


doc/source/admin/images/orig/sign-out-admin.png → doc/source/images/orig/sign-out-admin.png View File


doc/source/admin/images/orig/sign-out-user.png → doc/source/images/orig/sign-out-user.png View File


doc/source/admin/images/orig/submit-1001.png → doc/source/images/orig/submit-1001.png View File


doc/source/admin/images/profile.png → doc/source/images/profile.png View File


doc/source/admin/images/recheck-1002.png → doc/source/images/recheck-1002.png View File


doc/source/admin/images/register.png → doc/source/images/register.png View File


doc/source/admin/images/review-1001.png → doc/source/images/review-1001.png View File


doc/source/admin/images/review-1003.png → doc/source/images/review-1003.png View File


doc/source/admin/images/sign-in.png → doc/source/images/sign-in.png View File


doc/source/admin/images/sign-out-admin.png → doc/source/images/sign-out-admin.png View File


doc/source/admin/images/sign-out-user.png → doc/source/images/sign-out-user.png View File


doc/source/admin/images/sshkey.png → doc/source/images/sshkey.png View File


doc/source/admin/images/submit-1001.png → doc/source/images/submit-1001.png View File


+ 37
- 18
doc/source/index.rst View File

@@ -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

tutorials/users/index

.. toctree::
:maxdepth: 2

howtos/users/index

Zuul Admins
***********

.. toctree::
:maxdepth: 2

user/index
admin/index
developer/index
releasenotes
tutorials/admins/index

.. toctree::
:maxdepth: 1
:maxdepth: 2

howtos/admins/index

governance
Digging Deeper
**************

.. toctree::
:hidden:
:maxdepth: 2

discussions/index

.. toctree::
:maxdepth: 2

glossary
references/index

Indices and tables
==================
------------------

* :ref:`genindex`
* :ref:`search`
* :ref:`glossary`


doc/source/governance.rst → doc/source/overview/governance.rst View File


+ 9
- 0
doc/source/overview/index.rst View File

@@ -0,0 +1,9 @@
Overview
========

.. toctree::
:maxdepth: 2

governance
vulnerabilities
releasenotes

doc/source/releasenotes.rst → doc/source/overview/releasenotes.rst View File

@@ -1,4 +1,3 @@
=============
Release Notes
=============


doc/source/user/vulnerabilities.rst → doc/source/overview/vulnerabilities.rst View File


doc/source/admin/client.rst → doc/source/references/client.rst View File


doc/source/user/config.rst → doc/source/references/config.rst View File

@@ -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


doc/source/admin/connections.rst → doc/source/references/connections.rst View File


doc/source/developer/ansible.rst → doc/source/references/developer/ansible.rst View File


doc/source/developer/datamodel.rst → doc/source/references/developer/datamodel.rst View File


doc/source/developer/docs.rst → doc/source/references/developer/docs.rst View File


doc/source/developer/drivers.rst → doc/source/references/developer/drivers.rst View File


doc/source/developer/index.rst → doc/source/references/developer/index.rst View File


doc/source/developer/javascript.rst → doc/source/references/developer/javascript.rst View File


doc/source/developer/releasenotes.rst → doc/source/references/developer/releasenotes.rst View File


doc/source/developer/specs/container-build-resources.rst → doc/source/references/developer/specs/container-build-resources.rst View File


doc/source/developer/specs/index.rst → doc/source/references/developer/specs/index.rst View File


doc/source/developer/specs/kubernetes-operator.rst → doc/source/references/developer/specs/kubernetes-operator.rst View File


doc/source/developer/specs/logs.rst → doc/source/references/developer/specs/logs.rst View File


doc/source/developer/specs/multiple-ansible-versions.rst → doc/source/references/developer/specs/multiple-ansible-versions.rst View File


doc/source/developer/specs/tenant-scoped-admin-web-API.rst → doc/source/references/developer/specs/tenant-scoped-admin-web-API.rst View File


doc/source/developer/testing.rst → doc/source/references/developer/testing.rst View File


Some files were not shown because too many files changed in this diff

Loading…
Cancel
Save