docs: Random fixes

Remove an unnecessary 'toctree' from the index page and fix some
definition lists.

Signed-off-by: Stephen Finucane <stephen@that.guru>

diff --git a/docs/api/index.rst b/docs/api/index.rst
index b2e93e011c47c436b3137644591cde73160805ef..8248150906c2099101d57fc5dc8bed5c7c7775c2 100644 (file)
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 API Documentation
 =================
 

diff --git a/docs/deployment/index.rst b/docs/deployment/index.rst
index d7b3fa373c940e4abbf95278599f2413c814d195..984e8a5fa84adbf15d9cd9a3784be49b4973e84f 100644 (file)
--- a/docs/deployment/index.rst
+++ b/docs/deployment/index.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Deployment Documentation
 ========================
 

diff --git a/docs/development/api.rst b/docs/development/api.rst
index 3cfefdb89296d6b7baf371be3436ef9088f3e9d6..bcb1f695739497a07c62dea68cd4af262615749b 100644 (file)
--- a/docs/development/api.rst
+++ b/docs/development/api.rst
@@ -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`.

diff --git a/docs/development/index.rst b/docs/development/index.rst
index 4447453cf52bdbc125a75ecb45271d0308bc0531..7c3d80407e5c5c10548f1775f3fd94a934db7434 100644 (file)
--- a/docs/development/index.rst
+++ b/docs/development/index.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Development Documention
 =======================
 

diff --git a/docs/index.rst b/docs/index.rst
index 2c2b92d435c88cca810932fda9c3f874b904b123..9cbd6ebe9a20517f7dabbdfcf0d0291c3eaac0aa 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -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

diff --git a/docs/releases/index.rst b/docs/releases/index.rst
index 8ddaafb2c93840fdf48d0993404747e1ad0410fe..3549e30a1c333081e41e65ae5386aecd4f54cf69 100644 (file)
--- a/docs/releases/index.rst
+++ b/docs/releases/index.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Release Notes
 =============
 

diff --git a/docs/usage/delegation.rst b/docs/usage/delegation.rst
index 8b99871a1fe421a5afaf80ba4e4e39955af33bba..b9e620bb9ea535e6f51e947dcc32fd640502034f 100644 (file)
--- a/docs/usage/delegation.rst
+++ b/docs/usage/delegation.rst
@@ -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 ``+++``.

diff --git a/docs/usage/index.rst b/docs/usage/index.rst
index 79d10d8376e25b9717e77c8c238759f8d9aae310..9d7dcf019854864b43d0c05d8923cdd693565941 100644 (file)
--- a/docs/usage/index.rst
+++ b/docs/usage/index.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Usage Documentation
 ===================
 

diff --git a/docs/usage/overview.rst b/docs/usage/overview.rst
index cc193f3f232ee68a8ff031e4c458d8e3783c3629..1db3244e738f0152b5ad2b8a72c641fbde9beb60 100644 (file)
--- a/docs/usage/overview.rst
+++ b/docs/usage/overview.rst
@@ -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>
@@ -147,25 +152,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::
@@ -178,6 +179,7 @@ User
    Provide information on building a CI system that reports check results back
    to Patchwork.
 
+
 Collections
 -----------
 
@@ -207,6 +209,7 @@ To-do Lists
 
 Patchwork users can store a to-do list of patches.
 
+
 Events
 ------
 
@@ -215,146 +218,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