Merge pull request #22116 from melissawm/add-sphinx-design

MAINT,DOC: Remove sphinx-panels in favor of sphinx-design
numpy · Aug 16, 2022 · b6a3e83 · b6a3e83
2 parents c2ddceb + 9de446a
commit b6a3e83
Show file tree

Hide file tree

Showing 10 changed files with 89 additions and 80 deletions.
diff --git a/doc/source/_static/numpy.css b/doc/source/_static/numpy.css
@@ -64,25 +64,29 @@ Nat Methods 8, 441 (2011). https://doi.org/10.1038/nmeth.1618
 
 /* Main page overview cards */
 
-.intro-card {
+.sd-card {
   background: #fff;
   border-radius: 0;
   padding: 30px 10px 20px 10px;
   margin: 10px 0px;
 }
 
-.intro-card p.card-text {
+.sd-card .sd-card-header {
+  text-align: center;
+}
+
+.sd-card .sd-card-header .sd-card-text {
   margin: 0px;
 }
 
-.intro-card .card-img-top {
+.sd-card .sd-card-img-top {
   height: 52px;
   width: 52px;
   margin-left: auto;
   margin-right: auto;
 }
 
-.intro-card .card-header {
+.sd-card .sd-card-header {
   border: none;
   background-color: white;
   color: #150458 !important;
@@ -91,35 +95,37 @@ Nat Methods 8, 441 (2011). https://doi.org/10.1038/nmeth.1618
   padding: 2.5rem 0rem 0.5rem 0rem;
 }
 
-.intro-card .card-footer {
+.sd-card .sd-card-footer {
   border: none;
   background-color: white;
 }
 
-.intro-card .card-footer p.card-text {
+.sd-card .sd-card-footer .sd-card-text {
   max-width: 220px;
   margin-left: auto;
   margin-right: auto;
 }
 
-
-
 /* Dark theme tweaking */
-html[data-theme=dark] .intro-card img[src*='.svg'] {
+html[data-theme=dark] .sd-card img[src*='.svg'] {
     filter: invert(0.82) brightness(0.8) contrast(1.2);
 }
 
 /* Main index page overview cards */
-html[data-theme=dark] .shadow {
-    box-shadow: 0 .5rem 1rem rgba(250, 250, 250, .6) !important
+html[data-theme=dark] .sd-card {
+  background-color:var(--pst-color-background);
+}
+
+html[data-theme=dark] .sd-shadow-sm {
+    box-shadow: 0 .1rem 1rem rgba(250, 250, 250, .6) !important
 }
 
-html[data-theme=dark] .intro-card .card-header {
+html[data-theme=dark] .sd-card .sd-card-header {
   background-color:var(--pst-color-background);
   color: #150458 !important;
 }
 
-html[data-theme=dark] .intro-card .card-footer {
+html[data-theme=dark] .sd-card .sd-card-footer {
   background-color:var(--pst-color-background);
 }
 

diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -84,7 +84,7 @@ class PyTypeObject(ctypes.Structure):
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
     'sphinx.ext.mathjax',
-    'sphinx_panels',
+    'sphinx_design',
 ]
 
 skippable_extensions = [
@@ -200,11 +200,6 @@ def setup(app):
 html_last_updated_fmt = '%b %d, %Y'
 html_css_files = ["numpy.css"]
 html_context = {"default_mode": "light"}
-
-# Prevent sphinx-panels from loading bootstrap css, the pydata-sphinx-theme
-# already loads it
-panels_add_bootstrap_css = False
-
 html_use_modindex = True
 html_copy_source = False
 html_domain_indices = False

diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -34,76 +34,84 @@ fast operations on arrays, including mathematical, logical, shape manipulation,
 sorting, selecting, I/O, discrete Fourier transforms, basic linear algebra,
 basic statistical operations, random simulation and much more.
 
-.. panels::
-    :card: + intro-card text-center
-    :column: col-lg-6 col-md-6 col-sm-6 col-xs-12 d-flex
 
-    ---
-    :img-top: ../source/_static/index-images/getting_started.svg
 
-    Getting Started
-    ^^^^^^^^^^^^^^^
+.. grid:: 2
 
-    New to NumPy? Check out the Absolute Beginner's Guide. It contains an
-    introduction to NumPy's main concepts and links to additional tutorials.
+    .. grid-item-card::
+        :img-top: ../source/_static/index-images/getting_started.svg
 
-    +++
+        Getting Started
+        ^^^^^^^^^^^^^^^
 
-    .. link-button:: user/absolute_beginners
-        :type: ref
-        :text: To the absolute beginner's guide
-        :classes: btn-block btn-secondary stretched-link
-
-    ---
-    :img-top: ../source/_static/index-images/user_guide.svg
+        New to NumPy? Check out the Absolute Beginner's Guide. It contains an
+        introduction to NumPy's main concepts and links to additional tutorials.
 
-    User Guide
-    ^^^^^^^^^^
+        +++
 
-    The user guide provides in-depth information on the
-    key concepts of NumPy with useful background information and explanation.
+        .. button-ref:: user/absolute_beginners
+            :expand:
+            :color: secondary
+            :click-parent:
 
-    +++
+            To the absolute beginner's guide
 
-    .. link-button:: user
-        :type: ref
-        :text: To the user guide
-        :classes: btn-block btn-secondary stretched-link
+    .. grid-item-card::
+        :img-top: ../source/_static/index-images/user_guide.svg
 
-    ---
-    :img-top: ../source/_static/index-images/api.svg
+        User Guide
+        ^^^^^^^^^^
 
-    API Reference
-    ^^^^^^^^^^^^^
+        The user guide provides in-depth information on the
+        key concepts of NumPy with useful background information and explanation.
 
-    The reference guide contains a detailed description of the functions,
-    modules, and objects included in NumPy. The reference describes how the
-    methods work and which parameters can be used. It assumes that you have an
-    understanding of the key concepts.
+        +++
 
-    +++
+        .. button-ref:: user
+            :expand:
+            :color: secondary
+            :click-parent:
 
-    .. link-button:: reference
-        :type: ref
-        :text: To the reference guide
-        :classes: btn-block btn-secondary stretched-link
+            To the user guide
 
-    ---
-    :img-top: ../source/_static/index-images/contributor.svg
+    .. grid-item-card::
+        :img-top: ../source/_static/index-images/api.svg
 
-    Contributor's Guide
-    ^^^^^^^^^^^^^^^^^^^
+        API Reference
+        ^^^^^^^^^^^^^
 
-    Want to add to the codebase? Can help add translation or a flowchart to the
-    documentation? The contributing guidelines will guide you through the
-    process of improving NumPy.
+        The reference guide contains a detailed description of the functions,
+        modules, and objects included in NumPy. The reference describes how the
+        methods work and which parameters can be used. It assumes that you have an
+        understanding of the key concepts.
 
-    +++
+        +++
 
-    .. link-button:: devindex
-        :type: ref
-        :text: To the contributor's guide
-        :classes: btn-block btn-secondary stretched-link
+        .. button-ref:: reference
+            :expand:
+            :color: secondary
+            :click-parent:
+
+            To the reference guide
+
+    .. grid-item-card::
+        :img-top: ../source/_static/index-images/contributor.svg
+
+        Contributor's Guide
+        ^^^^^^^^^^^^^^^^^^^
+
+        Want to add to the codebase? Can help add translation or a flowchart to the
+        documentation? The contributing guidelines will guide you through the
+        process of improving NumPy.
+
+        +++
+
+        .. button-ref:: devindex
+            :expand:
+            :color: secondary
+            :click-parent:
+
+            To the contributor's guide
 
 .. This is not really the index page, that is found in
    _templates/indexcontent.html The toctree content here will be added to the

diff --git a/doc/source/reference/arrays.interface.rst b/doc/source/reference/arrays.interface.rst
@@ -125,7 +125,7 @@ This approach to the interface consists of the object having an
        **Default**: ``[('', typestr)]``
 
    **data** (optional)
-       A 2-tuple whose first argument is a :doc:`Python integer <c-api/long>`
+       A 2-tuple whose first argument is a :doc:`Python integer <python:c-api/long>`
        that points to the data-area storing the array contents.
 
        .. note::
@@ -253,7 +253,7 @@ flag is present.
 .. note::
 
     :obj:`__array_struct__` is considered legacy and should not be used for new
-    code. Use the :py:doc:`buffer protocol <c-api/buffer>` or the DLPack protocol
+    code. Use the :doc:`buffer protocol <python:c-api/buffer>` or the DLPack protocol
     `numpy.from_dlpack` instead.
 
 

diff --git a/doc/source/user/basics.interoperability.rst b/doc/source/user/basics.interoperability.rst
@@ -44,7 +44,7 @@ objects to be treated as NumPy arrays whenever possible. When NumPy functions
 encounter a foreign object, they will try (in order):
 
 1. The buffer protocol, described :py:doc:`in the Python C-API documentation
-   <c-api/buffer>`.
+   <python:c-api/buffer>`.
 2. The ``__array_interface__`` protocol, described
    :ref:`in this page <arrays.interface>`. A precursor to Python's buffer
    protocol, it defines a way to access the contents of a NumPy array from other

diff --git a/doc/source/user/how-to-how-to.rst b/doc/source/user/how-to-how-to.rst
@@ -105,7 +105,7 @@ deep dives intended to give understanding rather than immediate assistance,
 and `References`, which give complete, authoritative data on some concrete
 part of NumPy (like its API) but aren't obligated to paint a broader picture.
 
-For more on tutorials, see :doc:`content/tutorial-style-guide`
+For more on tutorials, see :doc:`numpy-tutorials:content/tutorial-style-guide`
 
 ******************************************************************************
 Is this page an example of a how-to?

diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst
@@ -1485,4 +1485,4 @@ Further reading
 -  `SciPy Tutorial <https://docs.scipy.org/doc/scipy/reference/tutorial/index.html>`__
 -  `SciPy Lecture Notes <https://scipy-lectures.org>`__
 -  A `matlab, R, IDL, NumPy/SciPy dictionary <http://mathesaurus.sf.net/>`__
--  :doc:`tutorial-svd <content/tutorial-svd>`
+-  :doc:`tutorial-svd <numpy-tutorials:content/tutorial-svd>`
diff --git a/doc_requirements.txt b/doc_requirements.txt
@@ -2,7 +2,7 @@
 sphinx>=4.5.0
 numpydoc==1.4
 pydata-sphinx-theme==0.9.0
-sphinx-panels
+sphinx-design
 ipython!=8.1.0
 scipy
 matplotlib

diff --git a/environment.yml b/environment.yml
@@ -23,7 +23,7 @@ dependencies:
   - typing_extensions>=4.2.0
   # For building docs
   - sphinx>=4.5.0
-  - sphinx-panels
+  - sphinx-design
   - numpydoc=1.4.0
   - ipython
   - scipy

diff --git a/numpy/core/_add_newdocs.py b/numpy/core/_add_newdocs.py
@@ -1756,9 +1756,9 @@
     In such cases, the use of `numpy.linspace` should be preferred.
 
     The built-in :py:class:`range` generates :std:doc:`Python built-in integers
-    that have arbitrary size <c-api/long>`, while `numpy.arange` produces
-    `numpy.int32` or `numpy.int64` numbers. This may result in incorrect
-    results for large integer values::
+    that have arbitrary size <python:c-api/long>`, while `numpy.arange`
+    produces `numpy.int32` or `numpy.int64` numbers. This may result in
+    incorrect results for large integer values::
 
       >>> power = 40
       >>> modulo = 10000