@@ -1,3 +1,5 @@
+:orphan:
+
API Documentation
=================
@@ -1,3 +1,5 @@
+:orphan:
+
Deployment Documentation
========================
@@ -1,3 +1,5 @@
+:orphan:
+
Using the APIs
==============
@@ -5,6 +7,6 @@ Patchwork provides two APIs: the legacy :doc:`XML-RPC API <../api/xmlrpc>` and
the :doc:`REST API <../api/rest>`. You can use these APIs to interact with
Patchwork programmatically and to develop your own clients.
-For quick usage examples of the APIs, refer to the :ref:`documentation
-<api-docs>`. For examples of existing clients, refer to
+For quick usage examples of the APIs, refer to the :doc:`documentation
+<../api/index>`. For examples of existing clients, refer to
:doc:`../usage/clients`.
@@ -1,3 +1,5 @@
+:orphan:
+
Development Documention
=======================
@@ -17,8 +17,6 @@ subsystems of the Linux kernel. Although Patchwork has been developed with the
kernel workflow in mind, the aim is to be flexible enough to suit the majority
of community projects.
-.. _user-docs:
-
.. toctree::
:maxdepth: 2
:caption: Usage Documentation
@@ -29,8 +27,6 @@ of community projects.
usage/headers
usage/clients
-.. _deployment-docs:
-
.. toctree::
:maxdepth: 2
:caption: Deployment Documentation
@@ -40,8 +36,6 @@ of community projects.
deployment/management
deployment/upgrading
-.. _development-docs:
-
.. toctree::
:maxdepth: 2
:caption: Development Documentation
@@ -52,8 +46,6 @@ of community projects.
development/api
development/assets
-.. _api-docs:
-
.. toctree::
:maxdepth: 2
:caption: API Documentation
@@ -61,8 +53,6 @@ of community projects.
api/rest
api/xmlrpc
-.. _release-note-docs:
-
.. toctree::
:maxdepth: 2
:caption: Release Notes
@@ -72,12 +62,3 @@ of community projects.
releases/cashmere
releases/burlap
releases/alpaca
-
-.. toctree::
- :hidden:
-
- usage/index
- deployment/index
- development/index
- api/index
- releases/index
@@ -1,3 +1,5 @@
+:orphan:
+
Release Notes
=============
@@ -17,17 +17,14 @@ configured in the project administration page. This can usually be found at:
In this section there are the following fields:
User
-
The patchwork user that should be autodelegated to the patch
Priority
-
The priority of the rule relative to other patches. Higher values indicate
higher priority. If two rules have the same priority, ordering will be based
on the path.
Path
-
A path in `fnmatch`__ format. The fnmatch library allows for limited, Unix
shell-style wildcarding. Filenames are extracted from patch lines beginning
with ``---`` or ``+++``.
@@ -1,3 +1,5 @@
+:orphan:
+
Usage Documentation
===================
@@ -3,6 +3,9 @@ Overview
The key concepts or models of Patchwork are outlined below.
+.. contents::
+
+
Projects
--------
@@ -13,12 +16,14 @@ possible to have multiple projects in the same list using the subject as
filter. Patches, cover letters, and series are all associated with a single
project.
+
People
------
People are anyone who has submitted a patch, cover letter, or comment to a
Patchwork instance.
+
Users
-----
@@ -44,6 +49,7 @@ The operations that a maintainer can invoke include:
- Archive a patch
- Delegate a patch, or be delegated a patch
+
Submissions
-----------
@@ -70,14 +76,16 @@ not only the various aspects of the cover letter itself, such as the name and
body of the cover letter, but also various metadata associated with the email
that the cover letter was parsed from.
+
Comments
-~~~~~~~~
+--------
Comments are replies to a submission - either a patch or a cover letter. Unlike
a Mail User Agent (MUA) like Gmail, Patchwork does not thread comments.
Instead, every comment is associated with either a patch or a cover letter, and
organized by date.
+
Patch Metadata
--------------
@@ -115,20 +123,17 @@ or a comment on a patch. Patchwork extracts these tags at parse time and
associates them with the patch. You add extra tags to an email by replying to
the email. The following tags are available on a standard Patchwork install:
-Acked-by:
-
+``Acked-by:``
For example::
Acked-by: Stephen Finucane <stephen@that.guru>
-Tested-by:
-
+``Tested-by:``
For example::
Tested-by: Stephen Finucane <stephen@that.guru>
-Reviewed-by:
-
+``Reviewed-by:``
For example::
Reviewed-by: Stephen Finucane <stephen@that.guru>
@@ -159,25 +164,21 @@ Checks store the results of any tests executed (or executing) for a given
patch. This is useful, for example, when using a continuous integration (CI)
system to test patches. Checks have a number of fields associated with them:
-Context
-
+**Context**
A label to discern check from the checks of other testing systems
-Description
-
+**Description**
A brief, optional description of the check
-Target URL
-
+**Target URL**
A target URL where a user can find information related to this check, such as
test logs.
-State
-
- The state of the check. One of: pending, success, warning, fail
-
-User
+**State**
+ The state of the check. One of: ``pending``, ``success``, ``warning``,
+ ``fail``
+**User**
The user creating the check
.. note::
@@ -190,6 +191,7 @@ User
Provide information on building a CI system that reports check results back
to Patchwork.
+
Collections
-----------
@@ -219,6 +221,7 @@ To-do Lists
Patchwork users can store a to-do list of patches.
+
Events
------
@@ -227,146 +230,112 @@ Events are raised whenever patches are created or modified.
All events have a number of common properties, along with some event-specific
properties:
-`category`
-
+``category``
The type of event
-`project`
-
+``project``
The project this event belongs to
-`date`
-
+``date``
When this event was created
-.. note::
-
- Checks can only be created and read through the Patchwork APIs. Refer to
- `../api/index` for more information.
+``payload``
+ Additional information
Cover Letter Created
~~~~~~~~~~~~~~~~~~~~
-Sent when a cover letter is created.
-
-`category`
+:Category: ``cover-created``
- ``cover-created``
-
-`cover`
+Sent when a cover letter is created.
+``cover``
Created cover letter
Patch Created
~~~~~~~~~~~~~
-Sent when a patch is created.
-
-`category`
-
- ``patch-created``
+:Category: ``patch-created``
-`patch`
+Sent when a patch is created.
+``patch``
Created patch
Patch Completed
~~~~~~~~~~~~~~~
+:Category: ``patch-completed``
+
Sent when a patch in a series has its dependencies met, or when a patch that is
not in a series is created (since that patch has no dependencies).
-`category`
-
- ``patch-completed``
-
-`patch`
-
+``patch``
Completed patch
-`series`
-
+``series``
Series from which patch dependencies were extracted, if any
Patch Delegated
~~~~~~~~~~~~~~~
-Sent when a patch's delegate is changed.
-
-`category`
+:Category: ``patch-delegated``
- ``patch-delegated``
-
-`patch`
+Sent when a patch's delegate is changed.
+``patch``
Updated patch
-`previous`
-
+``previous``
Previous delegate, if any
-`current`
-
+``current``
Current delegate, if any
Patch State Changed
~~~~~~~~~~~~~~~~~~~
-Sent when a patch's state is changed.
-
-`category`
-
- ``patch-state-changed``
+:Category: ``patch-state-changed``
-`patch`
+Sent when a patch's state is changed.
+``patch``
Updated patch
-`previous`
-
+``previous``
Previous state
-`current`
-
+``current``
Current state
Check Created
~~~~~~~~~~~~~
-Sent when a patch check is created.
-
-`category`
-
- ``check-created``
+:Category: ``check-created``
-`check`
+Sent when a patch check is created.
+``check``
Created check
Series Created
~~~~~~~~~~~~~~
-Sent when a series is created.
+:Category: ``series-created``
-`category`
-
- ``series-created``
-
-`series`
+Sent when a series is created.
+``series``
Created series
Series Completed
~~~~~~~~~~~~~~~~
-Sent when a series is completed.
+:Category: ``series-completed``
-`category`
-
- ``series-completed``
-
-`series`
+Sent when a series is completed.
+``series``
Completed series
What's Not Exposed
Remove an unnecessary 'toctree' from the index page and fix some definition lists. Signed-off-by: Stephen Finucane <stephen@that.guru> --- docs/api/index.rst | 2 + docs/deployment/index.rst | 2 + docs/development/api.rst | 6 +- docs/development/index.rst | 2 + docs/index.rst | 19 ------ docs/releases/index.rst | 2 + docs/usage/delegation.rst | 3 - docs/usage/index.rst | 2 + docs/usage/overview.rst | 141 ++++++++++++++++++--------------------------- 9 files changed, 69 insertions(+), 110 deletions(-)