DOC add sphinx-prompt to ease select/copy/paste of prompt command scikit-learn#18512 (scikit-learn#18516)

Co-authored-by: Guillaume Lemaitre <[email protected]>

Author: HayesJohnD

build_tools/circle/build_doc.sh

@@ -182,6 +182,7 @@ conda create -n $CONDA_ENV_NAME --yes --quiet \
 source activate testenv
 pip install sphinx-gallery
 pip install numpydoc
+pip install sphinx-prompt
 
 # Set parallelism to 3 to overlap IO bound tasks with CPU bound tasks on CI
 # workers with 2 cores when building the compiled extensions of scikit-learn.

doc/computing/parallelism.rst

@@ -79,7 +79,9 @@ avoid oversubscription), the implementation will use as many threads as
 possible.
 
 You can control the exact number of threads that are used via the
-``OMP_NUM_THREADS`` environment variable::
+``OMP_NUM_THREADS`` environment variable:
+
+.. prompt:: bash $
 
     OMP_NUM_THREADS=4 python my_script.py
 

doc/conf.py

@@ -42,6 +42,7 @@
     'sphinx_gallery.gen_gallery',
     'sphinx_issues',
     'add_toctree_functions',
+    'sphinx-prompt',
 ]
 
 # this is needed for some reason...

doc/developers/advanced_installation.rst

@@ -26,7 +26,7 @@ Installing a nightly build is the quickest way to:
 
 - check whether a bug you encountered has been fixed since the last release.
 
-::
+.. prompt:: bash $
 
   pip install --pre --extra-index https://pypi.anaconda.org/scipy-wheels-nightly/simple scikit-learn
 
@@ -43,7 +43,9 @@ feature, code or documentation improvement).
 
 #. Use `Git <https://git-scm.com/>`_ to check out the latest source from the
    `scikit-learn repository <https://github.com/scikit-learn/scikit-learn>`_ on
-   Github.::
+   Github.:
+
+   .. prompt:: bash $
 
         git clone git://github.com/scikit-learn/scikit-learn.git  # add --depth 1 if your connection is slow
         cd scikit-learn
@@ -58,13 +60,17 @@ feature, code or documentation improvement).
 #. Optional (but recommended): create and activate a dedicated virtualenv_
    or `conda environment`_.
 
-#. Install Cython_ and build the project with pip in :ref:`editable_mode`::
+#. Install Cython_ and build the project with pip in :ref:`editable_mode`:
+
+   .. prompt:: bash $
 
         pip install cython
         pip install --verbose --no-build-isolation --editable .
 
 #. Check that the installed scikit-learn has a version number ending with
-   `.dev0`::
+   `.dev0`:
+
+   .. prompt:: bash $
 
     python -c "import sklearn; sklearn.show_versions()"
 
@@ -194,11 +200,15 @@ First, install `Build Tools for Visual Studio 2019
 Secondly, find out if you are running 64-bit or 32-bit Python. The building
 command depends on the architecture of the Python interpreter. You can check
 the architecture by running the following in ``cmd`` or ``powershell``
-console::
+console:
+
+.. prompt:: bash $
 
     python -c "import struct; print(struct.calcsize('P') * 8)"
 
-For 64-bit Python, configure the build environment with::
+For 64-bit Python, configure the build environment with:
+
+.. prompt:: bash $
 
     SET DISTUTILS_USE_SDK=1
     "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
@@ -209,7 +219,9 @@ Please be aware that the path above might be different from user to user. The
 aim is to point to the "vcvarsall.bat" file that will set the necessary
 environment variables in the current command prompt.
 
-Finally, build scikit-learn from this command prompt::
+Finally, build scikit-learn from this command prompt:
+
+.. prompt:: bash $
 
     pip install --verbose --no-build-isolation --editable .
 
@@ -233,12 +245,16 @@ If you use the conda package manager (version >= 4.7), you can install the
 ``compilers`` meta-package from the conda-forge channel, which provides
 OpenMP-enabled C/C++ compilers based on the llvm toolchain.
 
-First install the macOS command line tools::
+First install the macOS command line tools:
+
+.. prompt:: bash $
 
     xcode-select --install
 
 It is recommended to use a dedicated `conda environment`_ to build
-scikit-learn from source::
+scikit-learn from source:
+
+.. prompt:: bash $
 
     conda create -n sklearn-dev -c conda-forge python numpy scipy cython \
         joblib threadpoolctl pytest "compilers>=1.0.4,!=1.1.0" llvm-openmp
@@ -254,14 +270,18 @@ scikit-learn from source::
     problems for this setup.
 
 You can check that the custom compilers are properly installed from conda
-forge using the following command::
+forge using the following command:
 
-    conda list 
+.. prompt:: bash $
+
+    conda list
 
 which should include ``compilers`` and ``llvm-openmp``.
 
 The compilers meta-package will automatically set custom environment
-variables::
+variables:
+
+.. prompt:: bash $
 
     echo $CC
     echo $CXX
@@ -283,17 +303,23 @@ macOS compilers from Homebrew
 Another solution is to enable OpenMP support for the clang compiler shipped
 by default on macOS.
 
-First install the macOS command line tools::
+First install the macOS command line tools:
+
+.. prompt:: bash $
 
     xcode-select --install
 
 Install the Homebrew_ package manager for macOS.
 
-Install the LLVM OpenMP library::
+Install the LLVM OpenMP library:
+
+.. prompt:: bash $
 
     brew install libomp
 
-Set the following environment variables::
+Set the following environment variables:
+
+.. prompt:: bash $
 
     export CC=/usr/bin/clang
     export CXX=/usr/bin/clang++
@@ -303,7 +329,9 @@ Set the following environment variables::
     export LDFLAGS="$LDFLAGS -Wl,-rpath,/usr/local/opt/libomp/lib -L/usr/local/opt/libomp/lib -lomp"
 
 Finally, build scikit-learn in verbose mode (to check for the presence of the
-``-fopenmp`` flag in the compiler commands)::
+``-fopenmp`` flag in the compiler commands):
+
+.. prompt:: bash $
 
     make clean
     pip install --verbose --no-build-isolation --editable .
@@ -321,11 +349,15 @@ installed the scikit-learn Python development headers and a working C/C++
 compiler with OpenMP support (typically the GCC toolchain).
 
 Install build dependencies for Debian-based operating systems, e.g.
-Ubuntu::
+Ubuntu:
+
+.. prompt:: bash $
 
     sudo apt-get install build-essential python3-dev python3-pip
 
-then proceed as usual::
+then proceed as usual:
+
+.. prompt:: bash $
 
     pip3 install cython
     pip3 install --verbose --editable .
@@ -339,19 +371,25 @@ using an isolated environment, ``pip3`` should be replaced by ``pip`` in the
 above commands.
 
 When precompiled wheels of the runtime dependencies are not avalaible for your
-architecture (e.g. ARM), you can install the system versions::
+architecture (e.g. ARM), you can install the system versions:
+
+.. prompt:: bash $
 
     sudo apt-get install cython3 python3-numpy python3-scipy
 
-On Red Hat and clones (e.g. CentOS), install the dependencies using::
+On Red Hat and clones (e.g. CentOS), install the dependencies using:
+
+.. prompt:: bash $
 
     sudo yum -y install gcc gcc-c++ python3-devel numpy scipy
 
 Linux compilers from conda-forge
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Alternatively, install a recent version of the GNU C Compiler toolchain (GCC)
-in the user folder using conda::
+in the user folder using conda:
+
+.. prompt:: bash $
 
     conda create -n sklearn-dev -c conda-forge python numpy scipy cython \
         joblib threadpoolctl pytest compilers
@@ -365,19 +403,25 @@ FreeBSD
 
 The clang compiler included in FreeBSD 12.0 and 11.2 base systems does not
 include OpenMP support. You need to install the `openmp` library from packages
-(or ports)::
+(or ports):
+
+.. prompt:: bash $
 
     sudo pkg install openmp
 
 This will install header files in ``/usr/local/include`` and libs in
 ``/usr/local/lib``. Since these directories are not searched by default, you
-can set the environment variables to these locations::
+can set the environment variables to these locations:
+
+.. prompt:: bash $
 
     export CFLAGS="$CFLAGS -I/usr/local/include"
     export CXXFLAGS="$CXXFLAGS -I/usr/local/include"
     export LDFLAGS="$LDFLAGS -Wl,-rpath,/usr/local/lib -L/usr/local/lib -lomp"
 
-Finally, build the package using the standard command::
+Finally, build the package using the standard command:
+
+.. prompt:: bash $
 
     pip install --verbose --no-build-isolation --editable .
 
@@ -393,22 +437,30 @@ the base system and these steps will not be necessary.
 Alternative compilers
 =====================
 
-The command::
+The command:
+
+.. prompt:: bash $
 
     pip install --verbose --editable .
 
 will build scikit-learn using your default C/C++ compiler. If you want to build
 scikit-learn with another compiler handled by ``distutils`` or by
-``numpy.distutils``, use the following command::
+``numpy.distutils``, use the following command:
+
+.. prompt:: bash $
 
     python setup.py build_ext --compiler=<compiler> -i build_clib --compiler=<compiler>
 
-To see the list of available compilers run::
+To see the list of available compilers run:
+
+.. prompt:: bash $
 
     python setup.py build_ext --help-compiler
 
 If your compiler is not listed here, you can specify it via the ``CC`` and
-``LDSHARED`` environment variables (does not work on windows)::
+``LDSHARED`` environment variables (does not work on windows):
+
+.. prompt:: bash $
 
     CC=<compiler> LDSHARED="<compiler> -shared" python setup.py build_ext -i
 
@@ -417,26 +469,36 @@ Building with Intel C Compiler (ICC) using oneAPI on Linux
 
 Intel provides access to all of its oneAPI toolkits and packages through a
 public APT repository. First you need to get and install the public key of this
-repository::
+repository:
+
+.. prompt:: bash $
 
     wget https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS-2023.PUB
     sudo apt-key add GPG-PUB-KEY-INTEL-SW-PRODUCTS-2023.PUB
     rm GPG-PUB-KEY-INTEL-SW-PRODUCTS-2023.PUB
 
-Then, add the oneAPI repository to your APT repositories::
+Then, add the oneAPI repository to your APT repositories:
+
+.. prompt:: bash $
 
     sudo add-apt-repository "deb https://apt.repos.intel.com/oneapi all main"
     sudo apt-get update
 
-Install ICC, packaged under the name ``intel-oneapi-icc``::
+Install ICC, packaged under the name ``intel-oneapi-icc``:
+
+.. prompt:: bash $
 
     sudo apt-get install intel-oneapi-icc
 
-Before using ICC, you need to set up environment variables::
+Before using ICC, you need to set up environment variables:
+
+.. prompt:: bash $
 
     source /opt/intel/oneapi/setvars.sh
 
-Finally, you can build scikit-learn. For example on Linux x86_64::
+Finally, you can build scikit-learn. For example on Linux x86_64:
+
+.. prompt:: bash $
 
     python setup.py build_ext --compiler=intelem -i build_clib --compiler=intelem