[PATCH 2/9] docs: Convert README, index

Stephen Finucane stephen at that.guru
Tue Apr 11 09:27:44 AEST 2017 

We can remove the Markdown README but must keep the index page until all
docs are migrated.

Signed-off-by: Stephen Finucane <stephen at that.guru>
---
 README.md      | 88 --------------------------------------------------------
 README.rst     | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst | 80 ++++++++++++++++++++++++++++++++++++++++++++++-----
 3 files changed, 164 insertions(+), 95 deletions(-)
 delete mode 100644 README.md
 create mode 100644 README.rst

diff --git a/README.md b/README.md
deleted file mode 100644
index 488dad4..0000000
--- a/README.md
+++ /dev/null
@@ -1,88 +0,0 @@
-# Patchwork
-
-[![Requirements Status][badge-req-img]][badge-req-ref]
-[![Build Status][badge-travis-img]][badge-travis-ref]
-[![Code Health][badge-landscape-img]][badge-landscape-ref]
-[![Codecov][badge-codecov-img]][badge-codecov-ref]
-[![Docs Status][badge-doc-img]][badge-doc-ref]
-[![Stories in Ready][badge-waffle-img]][badge-waffle-ref]
-
-**Patchwork** is a patch tracking system for community-based projects. It is
-intended to make the patch management process easier for both the project's
-contributors and maintainers, leaving time for the more important (and more
-interesting) stuff.
-
-Patches that have been sent to a mailing list are "caught" by the system, and
-appear on a web page. Any comments posted that reference the patch are appended
-to the patch page too. The project's maintainer can then scan through the list
-of patches, marking each with a certain state, such as Accepted, Rejected or
-Under Review. Old patches can be sent to the archive or deleted.
-
-Currently, Patchwork is being used for a number of open-source projects, mostly
-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.
-
-# Development Installation
-
-[Docker][ref-docker] is the recommended installation methods for a Patchwork
-development environment. To install Patchwork:
-
-1. Install [**Docker**][ref-docker] and [**docker-compose**][ref-compose].
-2. Clone the Patchwork repo:
-
-        $ git clone https://github.com/getpatchwork/patchwork.git
-
-3. Build the images. This will download over 200MB from the internet:
-
-        $ docker-compose build
-
-4. Run `docker-compose up`:
-
-        $ docker-compose up
-
-The Patchwork instance will now be deployed at `http://localhost:8000/`.
-
-For more information, including helpful command line options and alternative
-installation methods, refer to the [development installation
-guide][docs-development].
-
-# Talks and Presentations
-
-* [**Mailing List, Meet CI**][pdf-fosdem-2] - FOSDEM 2017
-* [**A New Patchwork**][pdf-fosdem-1] - FOSDEM 2016
-* [**Patches carved into stone tablets**][pdf-stone-tools] - Kernel Recipes
-  Conference 2016
-* [**Patchwork: reducing your patch workload**][pdf-plumbers] - Linux Plumbers
-  Conference 2011
-
-# Additional Information
-
-For further information, please refer to the [docs][docs].
-
-# Contact
-
-For bug reports, patch submissions or other questions, please use the
-[Patchwork mailing list][pw-ml].
-
-[badge-codecov-ref]: https://codecov.io/gh/getpatchwork/patchwork
-[badge-codecov-img]: https://codecov.io/gh/getpatchwork/patchwork/branch/master/graph/badge.svg
-[badge-doc-ref]: https://patchwork.readthedocs.io/en/latest/
-[badge-doc-img]: https://readthedocs.org/projects/patchwork/badge/?version=latest
-[badge-landscape-ref]: https://landscape.io/github/getpatchwork/patchwork/master
-[badge-landscape-img]: https://landscape.io/github/getpatchwork/patchwork/master/landscape.svg?style=flat
-[badge-req-ref]: https://requires.io/github/getpatchwork/patchwork/requirements/?branch=master
-[badge-req-img]: https://requires.io/github/getpatchwork/patchwork/requirements.svg?branch=master
-[badge-travis-ref]: https://travis-ci.org/getpatchwork/patchwork
-[badge-travis-img]: https://travis-ci.org/getpatchwork/patchwork.svg?branch=master
-[badge-waffle-ref]: https://waffle.io/getpatchwork/patchwork
-[badge-waffle-img]: https://badge.waffle.io/getpatchwork/patchwork.svg?label=ready&title=Ready
-[docs]: https://patchwork.readthedocs.io/en/latest/
-[docs-development]: https://patchwork.readthedocs.io/en/latest/development/
-[pdf-fosdem-1]: https://speakerdeck.com/stephenfin/a-new-patchwork-bringing-ci-patch-tracking-and-more-to-the-mailing-list
-[pdf-fosdem-2]: https://speakerdeck.com/stephenfin/mailing-list-meet-ci
-[pdf-plumbers]: https://www.linuxplumbersconf.org/2011/ocw/system/presentations/255/original/patchwork.pdf
-[pdf-stone-tools]: https://github.com/gregkh/presentation-stone-tools/blob/34a3963/stone-tools.pdf
-[pw-ml]: https://ozlabs.org/mailman/listinfo/patchwork
-[ref-compose]: https://docs.docker.com/compose/install/
-[ref-docker]: https://docs.docker.com/engine/installation/linux/
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..5a94a77
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,91 @@
+=========
+Patchwork
+=========
+
+.. image:: https://requires.io/github/getpatchwork/patchwork/requirements/?branch=master
+   :target: https://requires.io/github/getpatchwork/patchwork/requirements.svg?branch=master
+   :alt: Requirements Status
+
+.. image:: https://codecov.io/gh/getpatchwork/patchwork/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/getpatchwork/patchwork
+   :alt: Codecov
+
+.. image:: https://landscape.io/github/getpatchwork/patchwork/master
+   :target: https://landscape.io/github/getpatchwork/patchwork/master/landscape.svg?style=flat
+   :alt: Code Health
+
+.. image:: https://travis-ci.org/getpatchwork/patchwork
+   :target: https://travis-ci.org/getpatchwork/patchwork.svg?branch=master
+   :alt: Build Status
+
+.. image:: https://readthedocs.org/projects/patchwork/badge/?version=latest
+   :target: http://patchwork.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation Status
+
+**Patchwork** is a patch tracking system for community-based projects. It is
+intended to make the patch management process easier for both the project's
+contributors and maintainers, leaving time for the more important (and more
+interesting) stuff.
+
+Patches that have been sent to a mailing list are "caught" by the system, and
+appear on a web page. Any comments posted that reference the patch are appended
+to the patch page too. The project's maintainer can then scan through the list
+of patches, marking each with a certain state, such as Accepted, Rejected or
+Under Review. Old patches can be sent to the archive or deleted.
+
+Currently, Patchwork is being used for a number of open-source projects, mostly
+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.
+
+Development Installation
+------------------------
+
+`Docker`_ is the recommended installation methods for a Patchwork
+development environment. To install Patchwork:
+
+1. Install **`Docker`_** and **`docker-compose`_**.
+
+2. Clone the Patchwork repo::
+
+       $ git clone https://github.com/getpatchwork/patchwork.git
+
+3. Build the images. This will download over 200MB from the internet::
+
+       $ docker-compose build
+
+4. Run `docker-compose up`::
+
+       $ docker-compose up
+
+The Patchwork instance will now be deployed at `http://localhost:8000/`.
+
+For more information, including helpful command line options and alternative
+installation methods, refer to the `documentation`_.
+
+Talks and Presentations
+-----------------------
+
+* **`Mailing List, Meet CI`_** - FOSDEM 2017
+
+* **`Patches carved into stone tablets`_** - Kernel Recipes Conference 2016
+
+* **`A New Patchwork`_** - FOSDEM 2016
+
+* **`Patchwork: reducing your patch workload`_** - Linux Plumbers Conference
+  2011
+
+Additional Information
+----------------------
+
+For further information, refer to the `documentation`_.
+
+Contact
+-------
+
+For bug reports, patch submissions or other questions, use the `mailing list`_.
+
+.. _docker-compose: https://docs.docker.com/compose/install/
+.. _Docker: https://docs.docker.com/engine/installation/linux/
+.. _documentation: https://patchwork.readthedocs.io/
+.. _mailing list: https://ozlabs.org/mailman/listinfo/patchwork
diff --git a/docs/index.rst b/docs/index.rst
index 2a9ce05..7a9ce09 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,15 +1,81 @@
-Welcome to Patchwork's documentation!
-=====================================
+Patchwork
+=========
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+Patchwork is a patch tracking system for community-based projects. It is
+intended to make the patch management process easier for both the project's
+contributors and maintainers, leaving time for the more important (and more
+interesting) stuff.
 
+Patches that have been sent to a mailing list are 'caught' by the system, and
+appear on a web page. Any comments posted that reference the patch are appended
+to the patch page too. The project's maintainer can then scan through the list
+of patches, marking each with a certain state, such as Accepted, Rejected or
+Under Review. Old patches can be sent to the archive or deleted.
 
-Indices and tables
-==================
+Currently, Patchwork is being used for a number of open-source projects, mostly
+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.
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+Download
+--------
+
+The latest version of Patchwork is available with git. To download:
+
+.. code-block:: shell
+
+   $ git clone git://github.com/getpatchwork/patchwork
+
+Patchwork is distributed under the `GNU General Public License (v2)`__.
+
+__ http://www.gnu.org/licenses/gpl-2.0.html
+
+Design
+------
+
+Patchwork should supplement mailing lists, not replace them
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Patchwork isn't intended to replace a community mailing list; that's why you
+can't comment on a patch in Patchwork. If this were the case, then there would
+be two forums of discussion on patches, which fragments the patch review
+process. Developers who don't use Patchwork would get left out of the
+discussion.
+
+However, a future development item for Patchwork is to facilitate on-list
+commenting, by providing a "send a reply to the list" feature for logged-in
+users.
+
+Don't pollute the project's changelogs with Patchwork poop
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A project's changelogs are valuable - we don't want to add Patchwork-specific
+metadata.
+
+Patchwork users shouldn't require a specific version control system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Not everyone uses git for kernel development, and not everyone uses git for
+Patchwork-tracked projects.
+
+It's still possible to hook other programs into Patchwork, using the pwclient
+command-line client for Patchwork, or directly to the XML RPC interface.
+
+Getting Started
+---------------
+
+You should check out the `deployment/installation` and
+`development/installation` guides for information on how to configure
+Patchwork for production and development environments, respectively.
+
+Support
+-------
+
+All questions and contributions should be sent to the
+`Patchwork mailing list`__
+
+__ https://ozlabs.org/mailman/listinfo/patchwork
-- 
2.9.3

More information about the Patchwork mailing list