Merge rst-toplevel-8054: Change the top level documents to be Restruc…

…tured Text, and make them otherwise nicer Author: hawkowl Reviewer: adiroiban Fixes: twisted#8054 git-svn-id: svn://svn.twistedmatrix.com/svn/Twisted/trunk@46217 bbbe8e31-12d6-0310-92fd-ac37d47ddeeb
fagan2888 · Nov 15, 2015 · dded0ae · dded0ae
1 parent 88589e1
commit dded0ae
Show file tree

Hide file tree

Showing 7 changed files with 150 additions and 164 deletions.
diff --git a/INSTALL b/INSTALL
diff --git a/INSTALL.rst b/INSTALL.rst
@@ -0,0 +1,42 @@
+Installing Twisted
+==================
+
+Installation Requirements
+-------------------------
+
+To install Twisted, you need:
+
+- Python 2.7 (full functionality) or 3.3/3.4/3.5 (subset of functionality).
+
+- `setuptools <https://pypi.python.org/pypi/setuptools>`_
+  (installed automatically if you use pip).
+
+- `Zope Interface <https://pypi.python.org/pypi/zope.interface>`_  3.6.0 or newer.
+  Zope Interface 4.0 or newer is required for Python 3.
+  Installing via pip will automatically download a suitable Zope Interface.
+
+- On Windows `pywin32 <https://pypi.python.org/pypi/pypiwin32>`_ is required.
+  Build 219 or later is highly recommended for reliable operation (this is already included in ActivePython).
+
+We also have `setuptools extras <http://twistedmatrix.com/documents/current/installation/howto/optional.html>`_ for automatically installing optional packages used by Twisted.
+
+
+Installing Twisted
+------------------
+
+To install the latest version of Twisted using pip::
+
+  $ pip install twisted
+
+You can install optional dependencies for specific functionality in Twisted (such as TLS or serial support) by using our setuptools extras (see above).
+
+As an example, to install Twisted with the TLS dependencies, use::
+
+  $ pip install twisted[tls]
+
+Additionally, there are packages available in the repositories of:
+
+- Debian and Ubuntu as ``python-twisted`` for Python 2.
+- FreeBSD as ``py-twisted`` for Python 2.
+- Arch as ``python-twisted`` for Python 2.
+- Fedora and RHEL as ``python-twisted`` for Python 2.
diff --git a/README b/README
diff --git a/README.rst b/README.rst
@@ -0,0 +1,98 @@
+Twisted 15.4.0
+==============
+
+|pypi|_
+|coverage|_
+
+Release Codename:
+
+    "Trial By Fire"
+
+For information on what's new in Twisted 15.4.0, see the `NEWS <NEWS>`_ file that comes with the distribution.
+
+
+What is this?
+-------------
+
+Twisted is an event-based framework for internet applications, supporting Python 2.7 and Python 3.3+.
+It includes modules for many different purposes, including the following:
+
+- ``twisted.web``: HTTP clients and servers, HTML templating, and a WSGI server
+- ``twisted.conch``: SSHv2 and Telnet clients and servers and terminal emulators
+- ``twisted.words``: Clients and servers for IRC, XMPP, and other IM protocols
+- ``twisted.mail``: IMAPv4, POP3, SMTP clients and servers
+- ``twisted.positioning``: Tools for communicating with NMEA-compatible GPS recievers
+- ``twisted.names``: DNS client and tools for making your own DNS servers
+- ``twisted.trial``: A unit testing framework that integrates well with Twisted-based code.
+
+Twisted supports all major system event loops -- ``select`` (all platforms), ``poll`` (most POSIX platforms), ``epoll`` (Linux), ``kqueue`` (FreeBSD, OS X), IOCP (Windows), and various GUI event loops (GTK+2/3, QT, wxWidgets).
+Third-party reactors can plug into Twisted, and provide support for additional event loops.
+
+
+Installing
+----------
+
+To install the latest version of Twisted using pip::
+
+  $ pip install twisted
+
+Additional instructions for installing this software are in `the installation instructions <INSTALL.rst>`_.
+
+
+Documentation and Support
+-------------------------
+
+Twisted's documentation is available from the `Twisted Matrix website <http://twistedmatrix.com/documents/current/>`_.
+This documentation contains how-tos, code examples, and an API reference.
+
+Help is also available on the `Twisted mailing list <http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python>`_.
+
+There is also a pair of very lively IRC channels, ``#twisted`` (for general Twisted questions) and ``#twisted.web`` (for Twisted Web), on ``chat.freenode.net``.
+
+
+Unit Tests
+----------
+
+Twisted has a comprehensive test suite, which can be run by ``tox``::
+
+  $ tox -l            # to view all test environments
+  $ tox -e py27-tests # to run the tests for Python 2.7
+  $ tox -e py34-tests # to run the tests for Python 3.4
+
+Some of these tests may fail if you:
+
+* don't have the dependencies required for a particular subsystem installed,
+* have a firewall blocking some ports (or things like Multicast, which Linux NAT has shown itself to do), or
+* run them as root.
+
+
+Copyright
+---------
+
+All of the code in this distribution is Copyright (c) 2001-2015 Twisted Matrix Laboratories.
+
+Twisted is made available under the MIT license.
+The included `LICENSE <LICENSE>`_ file describes this in detail.
+
+
+Warranty
+--------
+
+  THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
+  EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+  TO THE USE OF THIS SOFTWARE IS WITH YOU.
+
+  IN NO EVENT WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+  AND/OR REDISTRIBUTE THE LIBRARY, BE LIABLE TO YOU FOR ANY DAMAGES, EVEN IF
+  SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+  DAMAGES.
+
+Again, see the included `LICENSE <LICENSE>`_ file for specific legal details.
+
+
+.. |coverage| image:: https://codecov.io/github/twisted/twisted/coverage.svg?branch=trunk
+.. _coverage: https://codecov.io/github/twisted/twisted
+
+.. |pypi| image:: http://img.shields.io/pypi/v/twisted.svg
+.. _pypi: https://pypi.python.org/pypi/twisted
diff --git a/twisted/python/_release.py b/twisted/python/_release.py
@@ -389,7 +389,7 @@ def _makeNews(project, underTopfiles=True):
 
     # Then change the global version.
     twistedProject.updateVersion(newVersion)
-    _changeVersionInFile(oldVersion, newVersion, root.child('README').path)
+    _changeVersionInFile(oldVersion, newVersion, root.child('README.rst').path)
 
 
 

diff --git a/twisted/python/test/test_release.py b/twisted/python/test/test_release.py
@@ -353,7 +353,7 @@ def test_changeAllProjectVersions(self):
         """
         root = FilePath(self.mktemp())
         structure = {
-            "README": "Hi this is 1.0.0.",
+            "README.rst": "Hi this is 1.0.0.",
             "twisted": {
                 "topfiles": {
                     "README": "Hi this is 1.0.0"},
@@ -364,7 +364,7 @@ def test_changeAllProjectVersions(self):
         releaseDate = date(2010, 1, 1)
         changeAllProjectVersions(root, False, False, releaseDate)
         outStructure = {
-            "README": "Hi this is 10.0.0.",
+            "README.rst": "Hi this is 10.0.0.",
             "twisted": {
                 "topfiles": {
                     "README": "Hi this is 10.0.0"},
@@ -389,7 +389,7 @@ def test_changeAllProjectVersionsPreRelease(self):
                    "==================================\n"
                    "\n")
         structure = {
-            "README": "Hi this is 1.0.0pre1.",
+            "README.rst": "Hi this is 1.0.0pre1.",
             "NEWS": coreNews + webNews,
             "twisted": {
                 "topfiles": {
@@ -411,7 +411,7 @@ def test_changeAllProjectVersionsPreRelease(self):
                    "==============================\n"
                    "\n")
         outStructure = {
-            "README": "Hi this is 1.0.0.",
+            "README.rst": "Hi this is 1.0.0.",
             "NEWS": coreNews + webNews,
             "twisted": {
                 "topfiles": {
@@ -1542,7 +1542,7 @@ def test_twistedDistribution(self):
         """
         manInput1 = "pretend there's some troff in here or something"
         structure = {
-            "README": "Twisted",
+            "README.rst": "Twisted",
             "unrelated": "x",
             "LICENSE": "copyright!",
             "setup.py": "import toplevel",
@@ -1572,7 +1572,7 @@ def hasManpagesAndSphinx(path):
             return True
 
         outStructure = {
-            "README": "Twisted",
+            "README.rst": "Twisted",
             "unrelated": "x",
             "LICENSE": "copyright!",
             "setup.py": "import toplevel",
@@ -1666,7 +1666,7 @@ def test_buildAllTarballs(self):
         self._init(checkout)
 
         structure = {
-            "README": "Twisted",
+            "README.rst": "Twisted",
             "unrelated": "x",
             "LICENSE": "copyright!",
             "setup.py": "import toplevel",
@@ -1696,7 +1696,7 @@ def smellsLikeSphinxOutput(actual):
             return True
 
         twistedStructure = {
-            "README": "Twisted",
+            "README.rst": "Twisted",
             "unrelated": "x",
             "LICENSE": "copyright!",
             "setup.py": "import toplevel",
@@ -2025,7 +2025,7 @@ def test_export(self):
         repository as identical in a specified directory.
         """
         structure = {
-            "README": "Hi this is 1.0.0.",
+            "README.rst": "Hi this is 1.0.0.",
             "twisted": {
                 "topfiles": {
                     "README": "Hi this is 1.0.0"},

diff --git a/twisted/topfiles/8054.misc b/twisted/topfiles/8054.misc