From 57a72f3d6d3e3b0464f9b49ea07a095d78e3442e Mon Sep 17 00:00:00 2001 From: Roger Date: Wed, 15 Feb 2017 17:54:05 -0500 Subject: [PATCH 1/5] [3.6] Rename Doc/README.txt to Doc/README.rst and add formatting (GH-104) (cherry picked from commit b3f1f59cf451d4a25b204e7a24f7be4c95e40be8) --- Doc/Makefile | 2 +- Doc/{README.txt => README.rst} | 21 +++++++++++---------- Doc/conf.py | 2 +- Doc/make.bat | 2 +- README.rst | 4 ++-- 5 files changed, 16 insertions(+), 15 deletions(-) rename Doc/{README.txt => README.rst} (83%) diff --git a/Doc/Makefile b/Doc/Makefile index eb62df5b87cebe..94697f95671894 100644 --- 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 4f8e9f8f1417fb..dcd3d6e80ff3c4 100644 --- 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 . +documentation. You don't need to build them yourself, `prebuilt versions are +available `_. Documentation on authoring Python documentation, including information about -both style and markup, is available in the "Documenting Python" chapter of the -developers guide . +both style and markup, is available in the "`Documenting Python +`_" chapter of the +developers guide. Building the docs ================= -You need to have Sphinx installed; it is the toolset +You need to have `Sphinx `_ installed; it is the toolset used to build the docs. It is not included in this tree, but maintained -separately and available from PyPI . +separately and `available from PyPI `_. 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 `_. -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 `_. 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 b3f26d5a692163..18aebb68a8d8df 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -37,7 +37,7 @@ 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 d0b59618261011..b1a3738f309d3b 100644 --- a/Doc/make.bat +++ b/Doc/make.bat @@ -74,7 +74,7 @@ echo. Provided by this script: echo. clean, check, serve, htmlview echo. echo.All arguments past the first one are passed through to sphinx-build as -echo.filenames to build or are ignored. See README.txt in this directory or +echo.filenames to build or are ignored. See README.rst in this directory or echo.the documentation for your version of Sphinx for more exhaustive lists echo.of available targets and descriptions of each. echo. diff --git a/README.rst b/README.rst index d02ae64b7fc660..6f0dbd8c4068ad 100644 --- a/README.rst +++ b/README.rst @@ -130,8 +130,8 @@ If you would like to contribute to the development of Python, relevant documentation is available in the `Python Developer's Guide `_. -For information about building Python's documentation, refer to `Doc/README.txt -`_. +For information about building Python's documentation, refer to `Doc/README.rst +`_. Converting From Python 2.x to 3.x From 568f2378c36d80d6ab8b0f0a2283edcc4c7bc06e Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sat, 18 Feb 2017 12:01:47 +0530 Subject: [PATCH 2/5] Make devguide link in README more prominent (#145) (cherry picked from commit 1b3d88eb33085e90af729c4c2f78b5ba1b942b1e) --- README.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 6f0dbd8c4068ad..79356bbb21f3af 100644 --- a/README.rst +++ b/README.rst @@ -15,6 +15,13 @@ reserved. See the end of this file for further copyright and license information. +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 ------------ @@ -126,10 +133,6 @@ 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 -`_. - For information about building Python's documentation, refer to `Doc/README.rst `_. From bb25e345a3cd7b61e2f8ed9d6dc142aa2f318163 Mon Sep 17 00:00:00 2001 From: Paul Schreiber Date: Mon, 20 Feb 2017 08:08:59 -0500 Subject: [PATCH 3/5] README: OS X -> macOS (GH-55) (cherry picked from commit c0866855d54bbbe7bcac299c4af45389efacce0b) --- README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 79356bbb21f3af..fab713372eda54 100644 --- a/README.rst +++ b/README.rst @@ -35,7 +35,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 @@ -45,10 +45,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``. From 2da440bd4cc332517d3b3717ae2b3764484361fd Mon Sep 17 00:00:00 2001 From: Mariatta Date: Sat, 25 Feb 2017 08:59:26 -0800 Subject: [PATCH 4/5] README.rst: List out relevant links to the project (#283) (cherry picked from commit e32ec9334b35f897ace8a05128838f92c5e0b2fb) --- README.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.rst b/README.rst index fab713372eda54..e3e59fd27292dc 100644 --- a/README.rst +++ b/README.rst @@ -15,6 +15,15 @@ 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://cpython-devguide.readthedocs.io + Contributing to CPython ----------------------- From 56b9e52298c4492507d043a2d9f131ebd0d311f1 Mon Sep 17 00:00:00 2001 From: Mariatta Date: Sat, 25 Feb 2017 11:49:38 -0800 Subject: [PATCH 5/5] README.rst: Change the devguide url to docs.python.org/devguide (GH-295) (cherry picked from commit 6329aea78e3627d250009aa5aaaf47cd11587f4d) --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index e3e59fd27292dc..242572c5e361db 100644 --- a/README.rst +++ b/README.rst @@ -22,7 +22,7 @@ General Information - Source code: https://github.com/python/cpython - Issue tracker: https://bugs.python.org - Documentation: https://docs.python.org -- Developer's Guide: https://cpython-devguide.readthedocs.io +- Developer's Guide: https://docs.python.org/devguide/ Contributing to CPython -----------------------