From 3a36921c08455be27d3a5b069f5b918f426c22ec Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Fri, 16 Aug 2019 17:10:17 -0400 Subject: [PATCH 01/12] Add Sphinx roles to 'What's New and News Entries' --- committing.rst | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/committing.rst b/committing.rst index c8857b929..b3bd83a3d 100644 --- a/committing.rst +++ b/committing.rst @@ -204,9 +204,28 @@ column width should be used. There is no indentation or leading marker in the file (e.g. ``-``). There is also no need to start the entry with the issue number as it's part of the file name itself. Example news entry:: - Fix warning message when ``os.chdir()`` fails inside - ``test.support.temp_cwd()``. Patch by Chris Jerdonek. + Fix warning message when ``os.chdir()`` fails inside + ``test.support.temp_cwd()``. Patch by Chris Jerdonek. +In addition to inline reST, Misc/NEWS entries also support the usage of +`Sphinx roles `. Several +commonly used roles include :func:, :class:, and :meth:. When a +corresponding entry is found within the documentation, the text within +the role is converted into a hyperlink. Example news entry with Sphinx:: + + Fix warning message when :func:`os.chdir()` fails inside + :func:`test.support.temp_cwd()`. Patch by Chris Jerdonek. + +The inline Sphinx roles should be used to assist readers find more +information and context on the changes made. If the inline link does not +provide additional context, an inline reST code block should be used instead:: + + ```` + +Before using a Sphinx role, ensure that a corresponding entry exists +within the documentation. Also, ``build the HTML using make +``_ to +verify that the link leads to the correct location. Working with Git_ ----------------- From 3537389c6d5721fb397dab909d7b79f4a4a672f3 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Fri, 16 Aug 2019 19:18:20 -0400 Subject: [PATCH 02/12] Fix spacing --- committing.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/committing.rst b/committing.rst index b3bd83a3d..8fe25f251 100644 --- a/committing.rst +++ b/committing.rst @@ -217,14 +217,14 @@ the role is converted into a hyperlink. Example news entry with Sphinx:: :func:`test.support.temp_cwd()`. Patch by Chris Jerdonek. The inline Sphinx roles should be used to assist readers find more -information and context on the changes made. If the inline link does not -provide additional context, an inline reST code block should be used instead:: +information and context on the changes made. If the inline link does not +provide additional context, an inline reST code block should be used instead:: ```` Before using a Sphinx role, ensure that a corresponding entry exists -within the documentation. Also, ``build the HTML using make -``_ to +within the documentation. Also, `build the HTML using make +`_ to verify that the link leads to the correct location. Working with Git_ From 75f32b136b2595b33c0f9cfd41bebfbf47178e90 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Fri, 16 Aug 2019 19:19:25 -0400 Subject: [PATCH 03/12] Update committing.rst --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index 8fe25f251..e466daf61 100644 --- a/committing.rst +++ b/committing.rst @@ -223,7 +223,7 @@ provide additional context, an inline reST code block should be used instead:: ```` Before using a Sphinx role, ensure that a corresponding entry exists -within the documentation. Also, `build the HTML using make +within the documentation. Also, `build the HTML locally using make `_ to verify that the link leads to the correct location. From aa8006a6be151b811448f31aa5ba18483e6fd259 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Fri, 16 Aug 2019 19:20:29 -0400 Subject: [PATCH 04/12] Fix inline reST link --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index e466daf61..38af1e4f7 100644 --- a/committing.rst +++ b/committing.rst @@ -208,7 +208,7 @@ number as it's part of the file name itself. Example news entry:: ``test.support.temp_cwd()``. Patch by Chris Jerdonek. In addition to inline reST, Misc/NEWS entries also support the usage of -`Sphinx roles `. Several +`Sphinx roles `_. Several commonly used roles include :func:, :class:, and :meth:. When a corresponding entry is found within the documentation, the text within the role is converted into a hyperlink. Example news entry with Sphinx:: From a00d45d9c8e4f8c434ad323683c9f2575e6667c0 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Fri, 16 Aug 2019 19:22:49 -0400 Subject: [PATCH 05/12] Remove parens from Sphinx role --- committing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/committing.rst b/committing.rst index 38af1e4f7..889e1f191 100644 --- a/committing.rst +++ b/committing.rst @@ -213,8 +213,8 @@ commonly used roles include :func:, :class:, and :meth:. When a corresponding entry is found within the documentation, the text within the role is converted into a hyperlink. Example news entry with Sphinx:: - Fix warning message when :func:`os.chdir()` fails inside - :func:`test.support.temp_cwd()`. Patch by Chris Jerdonek. + Fix warning message when :func:`os.chdir` fails inside + :func:`test.support.temp_cwd`. Patch by Chris Jerdonek. The inline Sphinx roles should be used to assist readers find more information and context on the changes made. If the inline link does not From 5eb7d608492b6fa0857fb72eff800f1be05d9c0b Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Fri, 16 Aug 2019 19:24:33 -0400 Subject: [PATCH 06/12] Fix grammar --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index 889e1f191..3be3108b8 100644 --- a/committing.rst +++ b/committing.rst @@ -216,7 +216,7 @@ the role is converted into a hyperlink. Example news entry with Sphinx:: Fix warning message when :func:`os.chdir` fails inside :func:`test.support.temp_cwd`. Patch by Chris Jerdonek. -The inline Sphinx roles should be used to assist readers find more +The inline Sphinx roles should be used to assist readers in finding more information and context on the changes made. If the inline link does not provide additional context, an inline reST code block should be used instead:: From 294cd033f5cf3d034924aaf2cf29e42633dae27b Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Fri, 16 Aug 2019 19:28:12 -0400 Subject: [PATCH 07/12] Improve wording --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index 3be3108b8..197bf6413 100644 --- a/committing.rst +++ b/committing.rst @@ -222,7 +222,7 @@ provide additional context, an inline reST code block should be used instead:: ```` -Before using a Sphinx role, ensure that a corresponding entry exists +Before using any Sphinx roles, ensure that a corresponding entry exists within the documentation. Also, `build the HTML locally using make `_ to verify that the link leads to the correct location. From 87ab9fb5c45e2390bc9c20059caae6720c5e5f97 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Sat, 17 Aug 2019 00:28:10 -0400 Subject: [PATCH 08/12] Adjust wording Suggestion from Inada Naoki. --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index 197bf6413..f819cebe9 100644 --- a/committing.rst +++ b/committing.rst @@ -216,7 +216,7 @@ the role is converted into a hyperlink. Example news entry with Sphinx:: Fix warning message when :func:`os.chdir` fails inside :func:`test.support.temp_cwd`. Patch by Chris Jerdonek. -The inline Sphinx roles should be used to assist readers in finding more +The inline Sphinx roles can be used to assist readers in finding more information and context on the changes made. If the inline link does not provide additional context, an inline reST code block should be used instead:: From 4915d76aa0c6c7f8576e5e6d729d34f2443097c4 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Sun, 18 Aug 2019 05:30:07 -0400 Subject: [PATCH 09/12] Adjust wording and add "What's New" section. Adjust make HTML section to specify when it's needed and adjust wording to remove explicit recommendation to use the Sphinx roles by changing "should" -> "can". --- committing.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/committing.rst b/committing.rst index f819cebe9..6d9968cab 100644 --- a/committing.rst +++ b/committing.rst @@ -207,7 +207,7 @@ number as it's part of the file name itself. Example news entry:: Fix warning message when ``os.chdir()`` fails inside ``test.support.temp_cwd()``. Patch by Chris Jerdonek. -In addition to inline reST, Misc/NEWS entries also support the usage of +In addition to inline reST, news entries also support the usage of `Sphinx roles `_. Several commonly used roles include :func:, :class:, and :meth:. When a corresponding entry is found within the documentation, the text within @@ -218,14 +218,19 @@ the role is converted into a hyperlink. Example news entry with Sphinx:: The inline Sphinx roles can be used to assist readers in finding more information and context on the changes made. If the inline link does not -provide additional context, an inline reST code block should be used instead:: +provide additional context, an inline reST code block can be used instead:: ```` Before using any Sphinx roles, ensure that a corresponding entry exists -within the documentation. Also, `build the HTML locally using make +within the documentation. When editing multiple news entries at once in +"What's New" or Misc/NEWS.d/, `build the HTML locally using make `_ to -verify that the link leads to the correct location. +verify that the links lead to the correct locations. This does not need to be +done for individual PR news entries. + +The Sphinx roles provide the maximum benefit in "What's New" entries, +as they are read by the largest volume of users. Working with Git_ ----------------- From ed22f080b7dae3b673e34ae98ffa775022cf7f49 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Sun, 18 Aug 2019 17:01:21 -0400 Subject: [PATCH 10/12] Add suggestions from Inada Naoki Focus exclusively on news entries, adjust make HTML section, and mention that inline code blocks can be used as a substitute. --- committing.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/committing.rst b/committing.rst index 6d9968cab..3ae900ce0 100644 --- a/committing.rst +++ b/committing.rst @@ -223,14 +223,13 @@ provide additional context, an inline reST code block can be used instead:: ```` Before using any Sphinx roles, ensure that a corresponding entry exists -within the documentation. When editing multiple news entries at once in -"What's New" or Misc/NEWS.d/, `build the HTML locally using make +within the documentation. When adding rich formatting to news entries +`build the HTML locally using make `_ to -verify that the links lead to the correct locations. This does not need to be -done for individual PR news entries. +verify that the links lead to the correct locations. -The Sphinx roles provide the maximum benefit in "What's New" entries, -as they are read by the largest volume of users. +The Sphinx roles can be beneficial to readers, but they are not required. +Inline code blocks can be used as a viable substitute. Working with Git_ ----------------- From fd20a1c71c27cda8b53653314cfdd346d66bd0c7 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Wed, 21 Aug 2019 12:51:28 -0400 Subject: [PATCH 11/12] Update for netlify deploy preview --- committing.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/committing.rst b/committing.rst index 3ae900ce0..e658733d9 100644 --- a/committing.rst +++ b/committing.rst @@ -223,10 +223,11 @@ provide additional context, an inline reST code block can be used instead:: ```` Before using any Sphinx roles, ensure that a corresponding entry exists -within the documentation. When adding rich formatting to news entries -`build the HTML locally using make -`_ to -verify that the links lead to the correct locations. +within the documentation. When adding rich formatting to news entries, +use the netlify deploy preview to verify that the documentation was +appropriately modified. Alternatively, `make html +`_ +can be used instead. The Sphinx roles can be beneficial to readers, but they are not required. Inline code blocks can be used as a viable substitute. From b13ca8437567136cdad0223ace9ee3653ea6711e Mon Sep 17 00:00:00 2001 From: Inada Naoki Date: Thu, 22 Aug 2019 18:52:54 +0900 Subject: [PATCH 12/12] simplify --- committing.rst | 30 +++++++----------------------- documenting.rst | 3 +++ 2 files changed, 10 insertions(+), 23 deletions(-) diff --git a/committing.rst b/committing.rst index e658733d9..19191b03b 100644 --- a/committing.rst +++ b/committing.rst @@ -202,35 +202,19 @@ So a file name may be The contents of a news file should be valid reStructuredText. An 80 character column width should be used. There is no indentation or leading marker in the file (e.g. ``-``). There is also no need to start the entry with the issue -number as it's part of the file name itself. Example news entry:: - - Fix warning message when ``os.chdir()`` fails inside - ``test.support.temp_cwd()``. Patch by Chris Jerdonek. - -In addition to inline reST, news entries also support the usage of -`Sphinx roles `_. Several -commonly used roles include :func:, :class:, and :meth:. When a -corresponding entry is found within the documentation, the text within -the role is converted into a hyperlink. Example news entry with Sphinx:: +number as it's part of the file name itself. You can use +:ref:`inline markups ` too. Example news entry:: Fix warning message when :func:`os.chdir` fails inside :func:`test.support.temp_cwd`. Patch by Chris Jerdonek. -The inline Sphinx roles can be used to assist readers in finding more -information and context on the changes made. If the inline link does not -provide additional context, an inline reST code block can be used instead:: - - ```` +The inline Sphinx roles like ``:func:`` can be used to assist readers in finding +more information. You can build html and verify that the link target is +appropriate by using :ref:`make html `. -Before using any Sphinx roles, ensure that a corresponding entry exists -within the documentation. When adding rich formatting to news entries, -use the netlify deploy preview to verify that the documentation was -appropriately modified. Alternatively, `make html -`_ -can be used instead. +While Sphinx roles can be beneficial to readers, they are not required. +Inline ````code blocks```` can be used instead. -The Sphinx roles can be beneficial to readers, but they are not required. -Inline code blocks can be used as a viable substitute. Working with Git_ ----------------- diff --git a/documenting.rst b/documenting.rst index 1607889a2..0144c05b7 100644 --- a/documenting.rst +++ b/documenting.rst @@ -902,6 +902,7 @@ file :file:`example.py`, use:: The file name is relative to the current file's path. Documentation-specific include files should be placed in the ``Doc/includes`` subdirectory. +.. _rest-inline-markup: Inline markup ------------- @@ -1531,6 +1532,8 @@ created using ``make venv``), so that the Makefile can find the ``sphinx-build`` with the ``SPHINXBUILD`` :command:`make` variable. +.. _building-using-make: + Using make / make.bat ---------------------