From b13ca8437567136cdad0223ace9ee3653ea6711e Mon Sep 17 00:00:00 2001 From: Inada Naoki Date: Thu, 22 Aug 2019 18:52:54 +0900 Subject: [PATCH] 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 ---------------------