Merge pull request #19185 from MarsBarLee/crosslink-gitpod

DOC: Crosslinking to Gitpod guide

2 files changed, 82 insertions, 29 deletions

diff --git a/doc/source/docs/howto_build_docs.rst b/doc/source/docs/howto_build_docs.rst
index 38ea1338c..737f69877 100644
--- a/doc/source/docs/howto_build_docs.rst
+++ b/doc/source/docs/howto_build_docs.rst
@@ -16,6 +16,33 @@ in several different formats.
 
 .. _Sphinx: http://www.sphinx-doc.org/
 
+To build the documentation, you must first build NumPy.
+
+There are two options for building NumPy and its documentation- building with
+Gitpod or locally from source. Your choice depends on your operating system and
+familiarity with the command line.
+
+Gitpod
+------------
+
+Gitpod is an open-source platform that automatically creates
+the correct development environment right in your browser, reducing the need to
+install local development environments and deal with incompatible dependencies.
+
+If you are a Windows user, unfamiliar with using the command line or building
+NumPy's documentation for the first time, it is often faster to build with
+Gitpod. Here are the in-depth instructions for building NumPy with `building
+NumPy with Gitpod`_.
+
+.. _building NumPy with Gitpod: https://numpy.org/devdocs/dev/development_gitpod.html
+
+Building locally
+------------------
+
+Building locally on your machine gives you more granular control. If you are a
+MacOS or Linux user familiar with using the command line, you can continue with
+building NumPy locally by following the instructions below.
+
 
 Instructions
 ------------
diff --git a/doc/source/user/building.rst b/doc/source/user/building.rst
index 1d1286b42..10983ce8f 100644
--- a/doc/source/user/building.rst
+++ b/doc/source/user/building.rst
@@ -3,8 +3,30 @@
 Building from source
 ====================
 
-A general overview of building NumPy from source is given here, with detailed
-instructions for specific platforms given separately.
+There are two options for building NumPy- building with Gitpod or locally from
+source. Your choice depends on your operating system and familiarity with the
+command line.
+
+Gitpod
+------------
+
+Gitpod is an open-source platform that automatically creates
+the correct development environment right in your browser, reducing the need to
+install local development environments and deal with incompatible dependencies.
+
+If you are a Windows user, unfamiliar with using the command line or building
+NumPy for the first time, it is often faster to build with Gitpod. Here are the
+in-depth instructions for building NumPy with `building NumPy with Gitpod`_.
+
+.. _building NumPy with Gitpod: https://numpy.org/devdocs/dev/development_gitpod.html
+
+Building locally
+------------------
+
+Building locally on your machine gives you
+more granular control. If you are a MacOS or Linux user familiar with using the
+command line, you can continue with building NumPy locally by following the
+instructions below.
 
 ..
   This page is referenced from numpy/numpy/__init__.py. Please keep its
@@ -23,15 +45,16 @@ Building NumPy requires the following software installed:
 
 2) Compilers
 
-   To build any extension modules for Python, you'll need a C compiler.
-   While a FORTRAN 77 compiler is not necessary for building NumPy, it is needed to run
-   the ``numpy.f2py`` tests. These tests are skipped if the compiler is not auto-detected.
+   While a FORTRAN 77 compiler is not necessary for building NumPy, it is
+   needed to run the ``numpy.f2py`` tests. These tests are skipped if the
+   compiler is not auto-detected.
 
    Note that NumPy is developed mainly using GNU compilers and tested on
    MSVC and Clang compilers. Compilers from other vendors such as Intel,
-   Absoft, Sun, NAG, Compaq, Vast, Portland, Lahey, HP, IBM are only supported
-   in the form of community feedback, and may not work out of the box.
-   GCC 4.x (and later) compilers are recommended. On ARM64 (aarch64) GCC 8.x (and later) are recommended.
+   Absoft, Sun, NAG, Compaq, Vast, Portland, Lahey, HP, IBM are only
+   supported in the form of community feedback, and may not work out of the
+   box.  GCC 4.x (and later) compilers are recommended. On ARM64 (aarch64)
+   GCC 8.x (and later) are recommended.
 
 3) Linear Algebra libraries
 
@@ -67,7 +90,8 @@ To perform an in-place build that can be run from the source folder run::
 Testing
 -------
 
-Make sure to test your builds. To ensure everything stays in shape, see if all tests pass::
+Make sure to test your builds. To ensure everything stays in shape, see if
+all tests pass::
 
     $ python runtests.py -v -m full
 
@@ -105,11 +129,12 @@ For more information see::
 How to check the ABI of BLAS/LAPACK libraries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-One relatively simple and reliable way to check for the compiler used to build
-a library is to use ldd on the library. If libg2c.so is a dependency, this
-means that g77 has been used (note: g77 is no longer supported for building NumPy).
-If libgfortran.so is a dependency, gfortran has been used. If both are dependencies,
-this means both have been used, which is almost always a very bad idea.
+One relatively simple and reliable way to check for the compiler used to
+build a library is to use ldd on the library. If libg2c.so is a dependency,
+this means that g77 has been used (note: g77 is no longer supported for
+building NumPy). If libgfortran.so is a dependency, gfortran has been used.
+If both are dependencies, this means both have been used, which is almost
+always a very bad idea.
 
 .. _accelerated-blas-lapack-libraries:
 
@@ -155,11 +180,11 @@ Alternatively one may use ``!`` or ``^`` to negate all items::
 
         NPY_BLAS_ORDER='^blas,atlas' python setup.py build
 
-will allow using anything **but** NetLIB BLAS and ATLAS libraries, the order of the above
-list is retained.
+will allow using anything **but** NetLIB BLAS and ATLAS libraries, the order
+of the above list is retained.
 
-One cannot mix negation and positives, nor have multiple negations, such cases will
-raise an error.
+One cannot mix negation and positives, nor have multiple negations, such
+cases will raise an error.
 
 LAPACK
 ~~~~~~
@@ -191,19 +216,19 @@ Alternatively one may use ``!`` or ``^`` to negate all items::
 
         NPY_LAPACK_ORDER='^lapack' python setup.py build
 
-will allow using anything **but** the NetLIB LAPACK library, the order of the above
-list is retained.
+will allow using anything **but** the NetLIB LAPACK library, the order of
+the above list is retained.
 
-One cannot mix negation and positives, nor have multiple negations, such cases will
-raise an error.
+One cannot mix negation and positives, nor have multiple negations, such
+cases will raise an error.
 
 .. deprecated:: 1.20
   The native libraries on macOS, provided by Accelerate, are not fit for use
-  in NumPy since they have bugs that cause wrong output under easily reproducible
-  conditions. If the vendor fixes those bugs, the library could be reinstated,
-  but until then users compiling for themselves should use another linear
-  algebra library or use the built-in (but slower) default, see the next
-  section.
+  in NumPy since they have bugs that cause wrong output under easily
+  reproducible conditions. If the vendor fixes those bugs, the library could
+  be reinstated, but until then users compiling for themselves should use
+  another linear algebra library or use the built-in (but slower) default,
+  see the next section.
 
 
 Disabling ATLAS and other accelerated libraries
@@ -257,5 +282,6 @@ Supplying additional compiler flags
 
 Additional compiler flags can be supplied by setting the ``OPT``,
 ``FOPT`` (for Fortran), and ``CC`` environment variables.
-When providing options that should improve the performance of the code ensure
-that you also set ``-DNDEBUG`` so that debugging code is not executed.
+When providing options that should improve the performance of the code
+ensure that you also set ``-DNDEBUG`` so that debugging code is not
+executed.