From 8f1c30c3a6b6a4ea7ea52ff9e6b4af2306f1f554 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 25 Jun 2024 11:21:38 +0200
Subject: [PATCH] Apply suggestions from code review

Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
---
 doc/usage/installation.rst | 35 +++++++++++++++++++++++++----------
 1 file changed, 25 insertions(+), 10 deletions(-)

diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst
index 06eb6e81757..29d4e7c24fb 100644
--- a/doc/usage/installation.rst
+++ b/doc/usage/installation.rst
@@ -21,15 +21,14 @@ This should print out the Sphinx version number.
 
 .. tip::
 
-   If you use Sphinx for documenting a Python library or application, it is
-   generally recommended to install Sphinx into your development environment
-   (`venv <https://docs.python.org/3/library/venv.html>`_ or `conda
-   <https://conda.io/projects/conda/en/latest/user-guide/getting-started.html>`_
-   environment).
-
-   By adding Sphinx and 3rdparty extensions or themes that you use to your dev
-   dependencies, you make sure that you have a consistent setup for building
-   your documentation.
+   For local development, it is
+   generally recommended to install Sphinx into a non-global environment
+   (using for example `venv`__ or `conda`__ environments).
+   This will allow for the use of separate sphinx versions and third-party extensions
+   for each sphinx project.
+   
+   __ https://docs.python.org/3/library/venv.html
+   __ https://conda.io/projects/conda/en/latest/user-guide/getting-started.html
 
 
 .. _install-pypi:
@@ -39,13 +38,29 @@ PyPI package
 
 Sphinx packages are published on the `Python Package Index
 <https://pypi.org/project/Sphinx/>`_ (PyPI).  The preferred tool for installing
-packages from *PyPI* is :command:`pip`, which is included in all modern versions of
+packages from PyPI is :command:`pip`, which is included in all modern versions of
 Python.
 
 Run the following command::
 
    $ pip install -U sphinx
 
+.. tip::
+
+   To avoid issues when rebuilding your environment,
+   it is advisable to pin sphinx and third-party extension
+   versions in a `requirements.txt file`__::
+   
+      $ pip install -r requirements.txt
+      
+   Or, if writing documentation for a Python package,
+   place the dependencies in the `pyproject.toml file`__::
+   
+      $ pip install .[docs]
+
+   __ https://pip.pypa.io/en/stable/reference/requirements-file-format/
+   __ https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#dependencies-optional-dependencies
+
 .. _install-conda:
 
 Conda package