diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst
index 817f0a1cff..fec76fa977 100644
--- a/documentation/start-documenting.rst
+++ b/documentation/start-documenting.rst
@@ -5,6 +5,14 @@
Getting started
===============
+.. raw:: html
+
+
+
.. highlight:: rest
The Python language has a substantial body of documentation, much of it
@@ -81,22 +89,24 @@ Create a virtual environment
----------------------------
.. _doc-create-venv-unix:
+.. _doc-create-venv-windows:
-**On Unix platforms** that support :program:`make`
-(including Linux, macOS and BSD),
-you can create a new :mod:`venv` with the required dependencies using::
+You can create a new :mod:`venv` with the required dependencies using:
- make venv
+.. tab:: Unix/macOS
-Building the docs with :program:`make` will automatically use this environment
-without you having to activate it.
+ .. code-block:: shell
-.. _doc-create-venv-windows:
+ make venv
+
+ Building the docs with :program:`make` will automatically use this environment
+ without you having to activate it.
+
+.. tab:: Windows
-**On Windows**, or if not using :program:`make`,
-`create a new virtual environment `__ manually.
-Always be sure to `activate this environment `__
-before building the documentation.
+ `Create a new virtual environment `__ manually.
+ Always be sure to `activate this environment `__
+ before building the documentation.
.. _building-using-make:
@@ -106,21 +116,36 @@ before building the documentation.
Build using make / make.bat
---------------------------
-A Unix ``Makefile`` is provided, :cpy-file:`Doc/Makefile`,
-along with a :cpy-file:`Doc/make.bat` batch file for Windows
-that attempts to emulate it as closely as practical.
+.. tab:: Unix/macOS
+
+ A Unix ``Makefile`` is provided, :cpy-file:`Doc/Makefile`.
+
+.. tab:: Windows
+
+ A Windows ``make.bat`` is provided, :cpy-file:`Doc/make.bat`, which
+ attempts to emulate the Unix ``Makefile`` as closely as practical.
+
+ .. important::
+
+ The Windows ``make.bat`` batch file lacks a ``make venv`` target.
+ Instead, it automatically installs any missing dependencies
+ into the currently activated environment (or the base Python, if none).
+ Make sure the environment you :ref:`created above `
+ is `activated `__ before running ``make.bat``.
+
+To build the docs as HTML, run:
-.. important::
+.. tab:: Unix/macOS
- The Windows ``make.bat`` batch file lacks a ``make venv`` target.
- Instead, it automatically installs any missing dependencies
- into the currently activated environment (or the base Python, if none).
- Make sure the environment you :ref:`created above `
- is `activated `__ before running ``make.bat``.
+ .. code-block:: shell
-To build the docs as HTML, run::
+ make html
- make html
+.. tab:: Windows
+
+ .. code-block:: dosbatch
+
+ .\make html
.. tip:: * Replace ``html`` with ``htmlview`` to open the docs in a web browser
once the build completes.
@@ -129,13 +154,33 @@ To build the docs as HTML, run::
browser when you make changes to reST files (Unix only).
To check the docs for common errors with `Sphinx Lint`_
-(which is run on all :ref:`pull requests `), use::
+(which is run on all :ref:`pull requests `), use:
+
+.. tab:: Unix/macOS
+
+ .. code-block:: shell
+
+ make check
+
+.. tab:: Windows
+
+ .. code-block:: dosbatch
+
+ .\make check
+
+To list other supported :program:`make` targets, run:
+
+.. tab:: Unix/macOS
+
+ .. code-block:: shell
+
+ make help
- make check
+.. tab:: Windows
-To list other supported :program:`make` targets, run::
+ .. code-block:: dosbatch
- make help
+ .\make help
See :cpy-file:`Doc/README.rst` for more information.