[3.6] Backport README.rst changes (GH-294)

(cherry picked from commit b3f1f59cf451d4a25b204e7a24f7be4c95e40be8)
(cherry picked from commit 1b3d88eb33085e90af729c4c2f78b5ba1b942b1e)
(cherry picked from commit c0866855d54bbbe7bcac299c4af45389efacce0b)
(cherry picked from commit e32ec9334b35f897ace8a05128838f92c5e0b2fb)
(cherry picked from commit 6329aea78e3627d250009aa5aaaf47cd11587f4d)

diff --git a/Doc/Makefile b/Doc/Makefile
index eb62df5b87cebebd28106ef8cb1919e32cbb6edf..94697f956718943973696c09febbb312b83c7fcb 100644 (file)
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -153,7 +153,7 @@ dist:
        cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
 
 check:
-       $(PYTHON) tools/rstlint.py -i tools -i venv
+       $(PYTHON) tools/rstlint.py -i tools -i venv -i README.rst
 
 serve:
        ../Tools/scripts/serve.py build/html

diff --git a/Doc/README.txt b/Doc/README.rst
similarity index 83%
rename from Doc/README.txt
rename to Doc/README.rst
index 4f8e9f8f1417fbc2de630e2759c6e35a83735a2b..dcd3d6e80ff3c48d9da289679ac50872c7bcb4bc 100644 (file)
--- a/Doc/README.txt
+++ b/Doc/README.rst
@@ -2,20 +2,21 @@ Python Documentation README
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This directory contains the reStructuredText (reST) sources to the Python
-documentation.  You don't need to build them yourself, prebuilt versions are
-available at <https://docs.python.org/dev/download.html>.
+documentation.  You don't need to build them yourself, `prebuilt versions are
+available <https://docs.python.org/dev/download.html>`_.
 
 Documentation on authoring Python documentation, including information about
-both style and markup, is available in the "Documenting Python" chapter of the
-developers guide <https://docs.python.org/devguide/documenting.html>.
+both style and markup, is available in the "`Documenting Python
+<https://docs.python.org/devguide/documenting.html>`_" chapter of the
+developers guide.
 
 
 Building the docs
 =================
 
-You need to have Sphinx <http://sphinx-doc.org/> installed; it is the toolset
+You need to have `Sphinx <http://sphinx-doc.org/>`_ installed; it is the toolset
 used to build the docs.  It is not included in this tree, but maintained
-separately and available from PyPI <https://pypi.python.org/pypi/Sphinx>.
+separately and `available from PyPI <https://pypi.python.org/pypi/Sphinx>`_.
 
 
 Using make
@@ -108,11 +109,11 @@ see the make targets above).
 Contributing
 ============
 
-Bugs in the content should be reported to the Python bug tracker at
-https://bugs.python.org.
+Bugs in the content should be reported to the 
+`Python bug tracker <https://bugs.python.org>`_.
 
-Bugs in the toolset should be reported in the Sphinx bug tracker at
-https://www.bitbucket.org/birkenfeld/sphinx/issues/.
+Bugs in the toolset should be reported in the 
+`Sphinx bug tracker <https://github.com/sphinx-doc/sphinx/issues>`_.
 
 You can also send a mail to the Python Documentation Team at docs@python.org,
 and we will process your request as soon as possible.

diff --git a/Doc/conf.py b/Doc/conf.py
index b3f26d5a692163abefccfc842d4480ec21596595..18aebb68a8d8dfc11bf085a0d27ccdac334d83ba 100644 (file)
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -37,7 +37,7 @@ highlight_language = 'python3'
 needs_sphinx = '1.2'
 
 # Ignore any .rst files in the venv/ directory.
-exclude_patterns = ['venv/*']
+exclude_patterns = ['venv/*', 'README.rst']
 
 
 # Options for HTML output

diff --git a/Doc/make.bat b/Doc/make.bat
index d0b5961826101126b218885092e2448b872339b9..b1a3738f309d3b540b4652607f63fec5fa71bbcd 100644 (file)
--- a/Doc/make.bat
+++ b/Doc/make.bat
@@ -74,7 +74,7 @@ echo.   Provided by this script:
 echo.      clean, check, serve, htmlview\r
 echo.\r
 echo.All arguments past the first one are passed through to sphinx-build as\r
-echo.filenames to build or are ignored.  See README.txt in this directory or\r
+echo.filenames to build or are ignored.  See README.rst in this directory or\r
 echo.the documentation for your version of Sphinx for more exhaustive lists\r
 echo.of available targets and descriptions of each.\r
 echo.\r

diff --git a/README.rst b/README.rst
index d02ae64b7fc660644eb924b147d5d9f48579a8a0..242572c5e361db86a017a7e8b8a822282b54dc9a 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -15,6 +15,22 @@ reserved.
 
 See the end of this file for further copyright and license information.
 
+General Information
+-------------------
+
+- Website: https://www.python.org
+- Source code: https://github.com/python/cpython
+- Issue tracker: https://bugs.python.org
+- Documentation: https://docs.python.org
+- Developer's Guide: https://docs.python.org/devguide/
+
+Contributing to CPython
+-----------------------
+
+For more complete instructions on contributing to CPython development,
+see the `Developer Guide`_.
+
+.. _Developer Guide: https://docs.python.org/devguide/
 
 Using Python
 ------------
@@ -28,7 +44,7 @@ Installable Python kits, and information about using Python, are available at
 Build Instructions
 ------------------
 
-On Unix, Linux, BSD, OSX, and Cygwin::
+On Unix, Linux, BSD, macOS, and Cygwin::
 
     ./configure
     make
@@ -38,10 +54,10 @@ On Unix, Linux, BSD, OSX, and Cygwin::
 This will install Python as python3.
 
 You can pass many options to the configure script; run ``./configure --help``
-to find out more.  On OSX and Cygwin, the executable is called ``python.exe``;
+to find out more.  On macOS and Cygwin, the executable is called ``python.exe``;
 elsewhere it's just ``python``.
 
-On Mac OS X, if you have configured Python with ``--enable-framework``, you
+On macOS, if you have configured Python with ``--enable-framework``, you
 should use ``make frameworkinstall`` to do the installation.  Note that this
 installs the Python executable in a place that is not normally on your PATH,
 you may want to set up a symlink in ``/usr/local/bin``.
@@ -126,12 +142,8 @@ is downloadable in HTML, PDF, and reStructuredText formats; the latter version
 is primarily for documentation authors, translators, and people with special
 formatting requirements.
 
-If you would like to contribute to the development of Python, relevant
-documentation is available in the `Python Developer's Guide
-<https://docs.python.org/devguide/>`_.
-
-For information about building Python's documentation, refer to `Doc/README.txt
-<https://github.com/python/cpython/blob/3.6/Doc/README.txt>`_.
+For information about building Python's documentation, refer to `Doc/README.rst
+<https://github.com/python/cpython/blob/3.6/Doc/README.rst>`_.
 
 
 Converting From Python 2.x to 3.x