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 c8857b929b..b3bd83a3d8 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 b3bd83a3d8..8fe25f251c 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 8fe25f251c..e466daf61c 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 e466daf61c..38af1e4f75 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 38af1e4f75..889e1f1919 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 889e1f1919..3be3108b82 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 3be3108b82..197bf6413c 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 197bf6413c..f819cebe93 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 f819cebe93..6d9968cab5 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 6d9968cab5..3ae900ce04 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 3ae900ce04..e658733d9a 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 e658733d9a..19191b03bd 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 1607889a2c..0144c05b75 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 ---------------------