Use reStructuredText instead of Markdown

Github supports either, but the Python Package Index (PyPI) only
understands reStructuredText. The Sphinx documentation tool also prefers
reStructuredTest so we may as well use it throughout.

5 files changed, 252 insertions, 229 deletions

diff --git a/HACKING.mdwn b/HACKING.mdwn
deleted file mode 100644
index 4dcdc3b..0000000
--- a/HACKING.mdwn
+++ /dev/null
@@ -1,65 +0,0 @@
-The 'sandboxlib' library uses the PEP-8 coding style, as a guide.
-
-# Release process
-
-Basically, tag the commit you're going to release, build and upload a source
-distribution tarball to [PyPI], and then increment the version number.
-
-You need
-  - an account on PyPI with access to the 'sandboxlib' project
-  - push access to <https://github.com/codethinklabs/sandboxlib>
-
-Process:
-
-1. Run tests: `sudo tox`
-2. Create source distribution tarball: `python ./setup.py sdist`
-3. Upload to PyPI: `twine upload -u $PYPI_USERNAME -p $PYPI_PASSWORD dist/sandboxlib-0.0.0.tar.gz`
-4. Create and push tag: `git tag --annotate -m "sandboxlib version 0.0.0" 0.0.0 && git push --tags`
-
-I intend to follow [semantic versioning](http://www.semver.org/) and [PEP
-440](https://www.python.org/dev/peps/pep-0440/) when numbering versions of this
-library.
-
-For background on realising to the Python Package Index (PyPI), see:
-<https://packaging.python.org/en/latest/distributing.html>.
-
-[PyPI]: http://pypi.python.org/
-
-# Running the automated test suite
-
-Use `tox`. You'll need 'py.test', 'tox' and their dependencies available.
-
-Note that a lot of the tests will be skipped or fail if you don't run as
-'root', because some of the sandboxing backends only work when you are the
-'root' user. The test suite could handle this better than it does.
-
-You can also run `PYTHONPATH=. py.test`, which is quicker but only tests with
-a single version of Python, and runs in your host environment rather than a
-clean one managed by 'virtualenv'.
-
-# Testing that a sandbox conforms to the App Container spec
-
-The [App Container project] provides an 'ace' package containing a
-[validator application for App Container Executors (ACEs)].
-
-If you want to test whether a particular sandbox 'exec' module conforms to the
-App Container spec, try this. You'll need a [golang] compiler available, and you
-might need to set the `GOPATH` environment variable to point to a path where
-you're happy for Go to install dependencies.
-
-First build the `ace-validator-main.aci` and `ace-validator-sidekick.aci` App
-Container images.
-
-    git clone git://github.com/appc/spec appc-spec
-    cd appc-spec
-    ace/build
-    cd -
-
-Then, use the `run-sandbox` program from this repository to run the image:
-
-    run-sandbox appc-spec/ace/build/ace-validator-main.aci -e linux-user-chroot
-
-
-[App Container project]: https://github.com/appc/spec
-[validator application for App Container Executors (ACEs)]: https://github.com/appc/spec#validating-app-container-executors-aces
-[golang]: https://golang.org/doc/install
diff --git a/HACKING.rst b/HACKING.rst
new file mode 100644
index 0000000..a122fd0
--- /dev/null
+++ b/HACKING.rst
@@ -0,0 +1,69 @@
+The 'sandboxlib' library uses the PEP-8 coding style, as a guide.
+
+Release process
+---------------
+
+Basically, tag the commit you're going to release, build and upload a source
+distribution tarball to PyPI_, and then increment the version number.
+
+You need
+- an account on PyPI with access to the 'sandboxlib' project
+- push access to https://github.com/codethinklabs/sandboxlib
+
+Process:
+
+1. Run tests: ``sudo tox``
+2. Create source distribution tarball: ``python ./setup.py sdist``
+3. Upload to PyPI: ``twine upload -u $PYPI_USERNAME -p $PYPI_PASSWORD dist/sandboxlib-0.0.0.tar.gz``
+4. Create and push tag: ``git tag --annotate -m "sandboxlib version 0.0.0" 0.0.0 && git push --tags``
+
+I intend to follow `semantic versioning`_ and `PEP 440`_ when numbering
+versions of this library.
+
+For background on realising to the Python Package Index (PyPI), see:
+https://packaging.python.org/en/latest/distributing.html.
+
+.. _semantic versioning: <http://www.semver.org/>
+.. _PEP 440: https://www.python.org/dev/peps/pep-0440/
+.. _PyPI: http://pypi.python.org/
+
+Running the automated test suite
+--------------------------------
+
+Use ``tox``. You'll need 'py.test', 'tox' and their dependencies available.
+
+Note that a lot of the tests will be skipped or fail if you don't run as
+'root', because some of the sandboxing backends only work when you are the
+'root' user. The test suite could handle this better than it does.
+
+You can also run ``PYTHONPATH=. py.test``, which is quicker but only tests with
+a single version of Python, and runs in your host environment rather than a
+clean one managed by 'virtualenv'.
+
+Testing that a sandbox conforms to the App Container spec
+---------------------------------------------------------
+
+The `App Container project`_ provides an 'ace' package containing a
+`validator application for App Container Executors (ACEs)`_.
+
+If you want to test whether a particular sandbox 'exec' module conforms to the
+App Container spec, try this. You'll need a golang_ compiler available, and you
+might need to set the ``GOPATH`` environment variable to point to a path where
+you're happy for Go to install dependencies.
+
+First build the ``ace-validator-main.aci`` and ``ace-validator-sidekick.aci`` App
+Container images::
+
+    git clone git://github.com/appc/spec appc-spec
+    cd appc-spec
+    ace/build
+    cd -
+
+Then, use the ``run-sandbox`` program from this repository to run the image::
+
+    run-sandbox appc-spec/ace/build/ace-validator-main.aci -e linux-user-chroot
+
+
+.. _App Container project: https://github.com/appc/spec
+.. _validator application for App Container Executors (ACEs)`: https://github.com/appc/spec#validating-app-container-executors-aces
+.. _golang: https://golang.org/doc/install
diff --git a/README.mdwn b/README.mdwn
deleted file mode 100644
index 04a0ed8..0000000
--- a/README.mdwn
+++ /dev/null
@@ -1,163 +0,0 @@
-# sandboxlib: a lightweight library for running programs/commands in a sandbox
-
-This project is a total work in progress, no documentation yet.
-
-It is being developed as part of the [Baserock] project.
-
-The goal of this library is to provide the sandboxing functionality that is
-already present in the build tools [Morph] and [YBD]. We want this new library
-to be usable without depending on [linux-user-chroot], so that it can be used
-on Mac OS X, and hopefully other platforms too.
-
-A longer term goal is to become a useful, generic, cross-platform tool for
-running commands in an environment that is partially isolated from the host
-system in some way.
-
-The library is implemented in Python currently. This is mostly because it is
-an adaptation of existing Python code, not because of any desire to exclude
-other languages. Maybe we could rewrite it as a C library with Python bindings.
-
-SANDBOXLIB DOES NOT GUARANTEE YOU ANY KIND OF SECURITY. Its main purpose is
-for isolating software builds from the host system, to ensure that builds
-are not contacting the network, or reading or writing files outside the build
-environment.
-
-[Baserock]: http://www.baserock.org/
-[Morph]: http://wiki.baserock.org/Morph/
-[YBD]: https://github.com/devcurmudgeon/ybd/
-[linux-user-chroot]: https://git.gnome.org/browse/linux-user-chroot/tree/
-
-# Current backends
-
-  - chroot: any POSIX OS
-  - [linux-user-chroot] (plus `unshare`): Linux-only
-
-# Possible future backends
-
-  - [Security Enhanced Linux] (SELinux): see <https://danwalsh.livejournal.com/28545.html>
-  - [systemd-nspawn]
-
-[Security Enhanced Linux]: http://selinuxproject.org/page/Main_Page
-[systemd-nspawn]: http://www.freedesktop.org/software/systemd/man/systemd-nspawn.html
-
-# Relationship to other projects
-
-## Sandboxing
-
-### libsandbox / pysandbox
-
-The [libsandbox] library is a Linux-specific implementation of process
-sandboxing, which supports intercepting syscalls, calling setrlimit(),
-and dropping certain privileges.
-
-[libsandbox]: https://github.com/openjudge/sandbox
-
-### PRoot
-
-The [PRoot] tool provids features similar to [linux-user-chroot], plus some
-extra code to allow running programs for a different architecture using
-virtualisation. The PRoot tool is
-[discontinued](https://plus.google.com/107605112469213359575/posts/NA5GxX2DAHe).
-
-[PRoot]: http://proot.me/
-
-### seccomp
-
-The Linux kernel provides [seccomp] mode. This is a very restrictive sandbox
-in which most programs would not work at all. It is [used by Google
-Chrome](https://code.google.com/p/chromium/wiki/LinuxSandboxing#The_seccomp-bpf_sandbox),
-among other things.
-
-[seccomp]: https://en.wikipedia.org/wiki/Seccomp
-
-### Further reading
-
-  - [Sandboxing for multi-tenant applications](https://web.archive.org/web/20121129121538/http://blog.technologyofcontent.com/2011/04/sandboxing-for-multi-tenant-applications) (archived)
-  - [StackOverflow question "Run an untrusted C program in a sandbox in Linux that prevents it from opening files, forking, etc.?"](https://stackoverflow.com/questions/4249063/run-an-untrusted-c-program-in-a-sandbox-in-linux-that-prevents-it-from-opening-f)
-  - [StackOverflow question "How to "jail" a process without being root?"](https://unix.stackexchange.com/questions/6433/how-to-jail-a-process-without-being-root)
-
-## Containerisation
-
-There is a lot of overlap between the topics of 'containerisation' and
-'sandboxing'. Many tools that work with 'containers' expect that containers
-are long-lived things, where the 'sandboxlib' library treats a sandbox as a
-much more lightweight, temporary thing.
-
-### App Container spec
-
-I have been using the [App Container spec] as a reference during development.
-The scope of 'sandboxlib' is different to that of the App Container spec:
-'sandboxlib' only deals with a single, isolated sandbox (which may or may
-not be a 'container'), where the App Container spec is focused on multiple
-containers. However, 'sandboxlib' would be a useful building block for
-implementing a complete App Container runtime, and simple App Container images
-(.acis) should be runnable with the `run-sandbox` tool directly.
-
-[App Container spec]: https://github.com/appc/spec/
-
-### Docker
-
-[Docker] allows managing multiple prebuilt container systems. While it [can
-support multiple platform-specific backends](https://blog.docker.com/2014/03/docker-0-9-introducing-execution-drivers-and-libcontainer/)
-for running containers, I am only aware of Linux-specific backends at the time
-of writing.
-
-[Docker]: http://www.docker.io/
-
-### schroot
-
-The use case for the [schroot] tool is 'I want to define a contained
-environment once, and use it many times.' The 'sandboxlib' library is more
-about dynamically creating sandboxes. If [schroot] suits your needs, just
-use it directly without any abstraction layer.
-
-[schroot]: https://launchpad.net/schroot
-
-## Python-specific Sandboxing
-
-The 'sandboxlib' library is for sandboxing *any* program, at the operating
-system level.
-
-If you want to do language-level sandboxing (i.e. run untrusted Python code
-within a larger Python program), there are some ways to do it.
-
-The concensus seems to be that Python language-level sandboxing is pretty much
-impossible with the default 'cpython' Python runtime:
-
-  - <https://mail.python.org/pipermail/python-dev/2013-November/130132.html>
-  - <https://programmers.stackexchange.com/questions/191623/best-practices-for-execution-of-untrusted-code>
-
-However, other Python runtimes do support language-level sandboxing. [PyPy] is one:
-
-  - <https://pypy.readthedocs.org/en/latest/sandbox.html>
-
-[PyPy]: http://www.pypy.org/
-
-## Build tools
-
-### Bazel
-
-The [Bazel] build tool contains a [Linux-specific sandbox
-implementation](https://github.com/google/bazel/blob/master/src/main/tools/namespace-sandbox.c).
-
-[Bazel]: http://bazel.io/
-
-### Morph
-
-The [Morph] build tool (from [Baserock]) is the original source of the
-'sandboxlib' linux_user_chroot backend. Hopefully Morph will adopt the
-'sandboxlib' library in future.
-
-### YBD
-
-The [YBD] build tool (from [Baserock]) [triggered the creation of the
-'sandboxlib' library](https://github.com/devcurmudgeon/ybd/issues/32).
-
-# License
-
-License is GPLv2 but other licensing can be considered on request
-
-Most of the copyright is currently Codethink but don't let that put you off.
-There's no intent to keep this as a Codethink-only project, nor will there be
-any attempt to get folks to sign a contributor agreement. Contributors retain
-their own copyright.
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..c577200
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,182 @@
+============================================================================
+sandboxlib: a lightweight library for running programs/commands in a sandbox
+============================================================================
+
+This project is a total work in progress, no documentation yet.
+
+It is being developed as part of the Baserock_ project.
+
+The goal of this library is to provide the sandboxing functionality that is
+already present in the build tools Morph_ and YBD_. We want this new library
+to be usable without depending on linux-user-chroot_, so that it can be used
+on Mac OS X, and hopefully other platforms too.
+
+A longer term goal is to become a useful, generic, cross-platform tool for
+running commands in an environment that is partially isolated from the host
+system in some way.
+
+The library is implemented in Python currently. This is mostly because it is
+an adaptation of existing Python code, not because of any desire to exclude
+other languages. Maybe we could rewrite it as a C library with Python bindings.
+
+SANDBOXLIB DOES NOT GUARANTEE YOU ANY KIND OF SECURITY. Its main purpose is
+for isolating software builds from the host system, to ensure that builds
+are not contacting the network, or reading or writing files outside the build
+environment.
+
+.. _Baserock: http://www.baserock.org/
+.. _Morph: http://wiki.baserock.org/Morph/
+.. _YBD: https://github.com/devcurmudgeon/ybd/
+.. _linux-user-chroot: https://git.gnome.org/browse/linux-user-chroot/tree/
+
+Current backends
+================
+
+- chroot: any POSIX OS
+- linux-user-chroot_ (plus ``unshare``): Linux-only
+
+Possible future backends
+========================
+
+- `Security Enhanced Linux`_ (SELinux): see https://danwalsh.livejournal.com/28545.html
+- systemd-nspawn_
+
+.. _Security Enhanced Linux: http://selinuxproject.org/page/Main_Page
+.. _systemd-nspawn: http://www.freedesktop.org/software/systemd/man/systemd-nspawn.html
+
+Relationship to other projects
+==============================
+
+Sandboxing
+----------
+
+libsandbox / pysandbox
+~~~~~~~~~~~~~~~~~~~~~~
+
+The libsandbox_ library is a Linux-specific implementation of process
+sandboxing, which supports intercepting syscalls, calling setrlimit(),
+and dropping certain privileges.
+
+.. _libsandbox: https://github.com/openjudge/sandbox
+
+PRoot
+~~~~~
+
+The PRoot_ tool provids features similar to linux-user-chroot_, plus some
+extra code to allow running programs for a different architecture using
+virtualisation. The PRoot tool is `discontinued <https://plus.google.com/107605112469213359575/posts/NA5GxX2DAHe>`_.
+
+.. _PRoot: http://proot.me/
+
+seccomp
+~~~~~~~
+
+The Linux kernel provides seccomp_ mode. This is a very restrictive sandbox
+in which most programs would not work at all. It is `used by Google Chrome
+<https://code.google.com/p/chromium/wiki/LinuxSandboxing#The_seccomp-bpf_sandbox>`_,
+among other things.
+
+.. _seccomp: https://en.wikipedia.org/wiki/Seccomp
+
+Further reading
+~~~~~~~~~~~~~~~
+
+- `Sandboxing for multi-tenant applications <https://web.archive.org/web/20121129121538/http://blog.technologyofcontent.com/2011/04/sandboxing-for-multi-tenant-applications>`_ (archived)
+- `StackOverflow question "Run an untrusted C program in a sandbox in Linux that prevents it from opening files, forking, etc.? <https://stackoverflow.com/questions/4249063/run-an-untrusted-c-program-in-a-sandbox-in-linux-that-prevents-it-from-opening-f>`_
+- `StackOverflow question "How to "jail" a process without being root? <https://unix.stackexchange.com/questions/6433/how-to-jail-a-process-without-being-root>`_
+
+Containerisation
+----------------
+
+There is a lot of overlap between the topics of 'containerisation' and
+'sandboxing'. Many tools that work with 'containers' expect that containers
+are long-lived things, where the 'sandboxlib' library treats a sandbox as a
+much more lightweight, temporary thing.
+
+App Container spec
+~~~~~~~~~~~~~~~~~~
+
+I have been using the `App Container spec`_ as a reference during development.
+The scope of 'sandboxlib' is different to that of the App Container spec:
+'sandboxlib' only deals with a single, isolated sandbox (which may or may
+not be a 'container'), where the App Container spec is focused on multiple
+containers. However, 'sandboxlib' would be a useful building block for
+implementing a complete App Container runtime, and simple App Container images
+(.acis) should be runnable with the ``run-sandbox`` tool directly.
+
+.. _App Container spec: https://github.com/appc/spec/
+
+Docker
+~~~~~~
+
+Docker_ allows managing multiple prebuilt container systems. While it `can
+support multiple platform-specific backends <https://blog.docker.com/2014/03/docker-0-9-introducing-execution-drivers-and-libcontainer/>`_
+for running containers, I am only aware of Linux-specific backends at the time
+of writing.
+
+.. _Docker: http://www.docker.io/
+
+schroot
+~~~~~~~
+
+The use case for the schroot_ tool is 'I want to define a contained
+environment once, and use it many times.' The 'sandboxlib' library is more
+about dynamically creating sandboxes. If schroot_ suits your needs, just
+use it directly without any abstraction layer.
+
+.. _schroot: https://launchpad.net/schroot
+
+Python-specific Sandboxing
+--------------------------
+
+The 'sandboxlib' library is for sandboxing *any* program, at the operating
+system level.
+
+If you want to do language-level sandboxing (i.e. run untrusted Python code
+within a larger Python program), there are some ways to do it.
+
+The concensus seems to be that Python language-level sandboxing is pretty much
+impossible with the default 'cpython' Python runtime:
+
+- https://mail.python.org/pipermail/python-dev/2013-November/130132.html
+- https://programmers.stackexchange.com/questions/191623/best-practices-for-execution-of-untrusted-code
+
+However, other Python runtimes do support language-level sandboxing. PyPy_ is one:
+
+- https://pypy.readthedocs.org/en/latest/sandbox.html
+
+.. _PyPy: http://www.pypy.org/
+
+Build tools
+-----------
+
+Bazel
+~~~~~
+
+The Bazel_ build tool contains a `Linux-specific sandbox implementation
+<https://github.com/google/bazel/blob/master/src/main/tools/namespace-sandbox.c>`_.
+
+.. _Bazel: http://bazel.io/
+
+Morph
+~~~~~
+
+The Morph_ build tool (from Baserock_) is the original source of the
+'sandboxlib' linux_user_chroot backend. Hopefully Morph will adopt the
+'sandboxlib' library in future.
+
+YBD
+~~~
+
+The YBD_ build tool (from Baserock_) `triggered the creation of the
+'sandboxlib' library <https://github.com/devcurmudgeon/ybd/issues/32>`_.
+
+License
+-------
+
+License is GPLv2 but other licensing can be considered on request
+
+Most of the copyright is currently Codethink but don't let that put you off.
+There's no intent to keep this as a Codethink-only project, nor will there be
+any attempt to get folks to sign a contributor agreement. Contributors retain
+their own copyright.
diff --git a/setup.cfg b/setup.cfg
index aad4d4f..6076912 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -3,7 +3,7 @@ name = sandboxlib
 version = 0.1.0
 summary = Sandboxing Library for Python
 description-file =
-    README.mdwn
+    README.rst
 
 [files]
 packages =