Add conda-sphinx-theme to conda-build 3.27.x (#5073)

* switchig to new conda-sphinx-theme * fixing some mistakes that were introduced by copying files;
conda · Nov 28, 2023 · c8dce86 · c8dce86
1 parent 27ea32b
commit c8dce86
Show file tree

Hide file tree

Showing 16 changed files with 91 additions and 183 deletions.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,4 @@
+conda-sphinx-theme==0.1.2
 linkify-it-py==2.0.2
 myst-parser==2.0.0
 Pillow==10.0.1
@@ -7,8 +8,8 @@ ruamel.yaml==0.17.32
 Sphinx==7.2.6
 sphinx-argparse==0.4.0
 sphinx-autobuild==2021.3.14
-sphinx-rtd-theme==1.3.0
 sphinx-sitemap==2.5.1
+sphinx_design==0.5.0
 sphinxcontrib-applehelp==1.0.7
 sphinxcontrib-devhelp==1.0.5
 sphinxcontrib-htmlhelp==2.0.4

diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
diff --git a/docs/source/concepts/package-naming-conv.rst b/docs/source/concepts/package-naming-conv.rst
@@ -3,33 +3,35 @@ Package naming conventions
 ==========================
 
 To facilitate communication and documentation, conda observes the
-package naming conventions listed below.
-
-**Package name**
-    The name of a package, without any reference to a particular
-    version. Conda package names are normalized and they may contain
-    only lowercase alpha characters, numeric digits, underscores,
-    hyphens, or dots. In usage documentation, these are referred to
-    by ``package_name``.
-
-**Package version**
-    A version number or string, often similar to ``X.Y`` or
-    ``X.Y.Z``, but it may take other forms as well.
-
-**Build string**
-    An arbitrary string that identifies a particular build of a
-    package for conda. It may contain suggestive mnemonics, but
-    these are subject to change, and you should not rely on it or try
-    to parse it for any specific information.
-
-**Canonical name**
-    The package name, version, and build string joined together by
-    hyphens: name-version-buildstring. In usage documentation, these
-    are referred to by ``canonical_name``.
-
-**Filename**
-    Conda package filenames are canonical names, plus the suffix
-    ``.tar.bz2`` or ``.conda``.
+package naming conventions listed below:
+
+.. glossary::
+
+    Package name
+        The name of a package, without any reference to a particular
+        version. Conda package names are normalized and they may contain
+        only lowercase alpha characters, numeric digits, underscores,
+        hyphens, or dots. In usage documentation, these are referred to
+        by ``package_name``.
+
+    Package version
+        A version number or string, often similar to ``X.Y`` or
+        ``X.Y.Z``, but it may take other forms as well.
+
+    Build string
+        An arbitrary string that identifies a particular build of a
+        package for conda. It may contain suggestive mnemonics, but
+        these are subject to change, and you should not rely on it or try
+        to parse it for any specific information.
+
+    Canonical name
+        The package name, version, and build string joined together by
+        hyphens: name-version-buildstring. In usage documentation, these
+        are referred to by ``canonical_name``.
+
+    Filename
+        Conda package filenames are canonical names, plus the suffix
+        ``.tar.bz2`` or ``.conda``.
 
 The following figure compares a canonical name to a filename:
 

diff --git a/docs/source/concepts/recipe.rst b/docs/source/concepts/recipe.rst
@@ -2,10 +2,6 @@
 Conda-build recipes
 ===================
 
-.. contents::
-   :local:
-   :depth: 2
-
 To enable building `conda packages`_, :ref:`install and update conda
 and conda-build <install-conda-build>`.
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -50,6 +50,7 @@
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
     "sphinx_sitemap",
+    "sphinx_design",
 ]
 
 myst_heading_anchors = 3
@@ -104,23 +105,60 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "conda_sphinx_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    # The maximum depth of the table of contents tree. Set this to -1 to allow
+    # unlimited depth.
+    "navigation_depth": -1,
+    "show_prev_next": False,
+    # Navbar icon links
+    "navbar_start": ["navbar-logo"],
+    "use_edit_page_button": True,
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/conda/conda-build",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+        },
+        {
+            "name": "Element",
+            "url": "https://matrix.to/#/#conda-build:matrix.org",
+            "icon": "_static/element_logo.svg",
+            "type": "local",
+        },
+        {
+            "name": "Discourse",
+            "url": "https://conda.discourse.group/",
+            "icon": "fa-brands fa-discourse",
+            "type": "fontawesome",
+        },
+    ],
+}
+
+html_context = {
+    "github_user": "conda",
+    "github_repo": "conda-build",
+    "github_version": "main",
+    "doc_path": "docs/source",
+}
 
 html_short_title = "conda-build"
-html_show_sourcelink = False
-html_favicon = "conda-logo.png"
+# html_show_sourcelink = False
 html_extra_path = ["robots.txt"]
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
+
+# Custom CSS rules
+# html_style = "css/custom.css"
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -212,5 +250,3 @@
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
-
-html_style = "css/custom.css"
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,5 +1,3 @@
-.. _index:
-
 Conda-build documentation
 =========================
 

diff --git a/docs/source/resources/define-metadata.rst b/docs/source/resources/define-metadata.rst
@@ -4,11 +4,6 @@
 Defining metadata (meta.yaml)
 =============================
 
-.. contents::
-   :local:
-   :depth: 1
-
-
 All the metadata in the conda-build recipe is specified in the
 ``meta.yaml`` file. See the example below:
 

diff --git a/docs/source/resources/package-spec.rst b/docs/source/resources/package-spec.rst
@@ -2,10 +2,6 @@
 Conda package specification
 ===========================
 
-.. contents::
-   :local:
-   :depth: 1
-
 A conda package is an archive file that contains:
 
 * Metadata under the ``info/`` directory.
@@ -289,17 +285,15 @@ parts:
   three parts, the second part must be the exact version.
 
 .. list-table:: Version Special Characters
-   :widths: 10, 40, 40
+   :widths: 10 40 40
    :header-rows: 1
 
    * - Symbol
      - Meaning
      - Example
 
    * - <, >, <=, >=
-     - Relational operators on versions,
-
-       which are compared using `PEP-440 <https://www.python.org/dev/peps/pep-0440/>`_.
+     - Relational operators on versions, which are compared using `PEP-440 <https://www.python.org/dev/peps/pep-0440/>`_.
      - ``<=1.0`` matches 0.9, 0.9.1, and 1.0, but not 1.0.1.
 
    * - ==, and !=
@@ -315,16 +309,12 @@ parts:
      - ``1.0|1.2`` matches version 1.0 or 1.2.
 
    * - \*
-     - Matches 0 or more characters in the version string.
-
-       In terms of regular expressions, it is the same as ``r'.*'``.
+     - Matches 0 or more characters in the version string. In terms of regular expressions, it is the same as ``r'.*'``.
      - ``1.0|1.4*`` matches 1.0, 1.4 and 1.4.1b2, but not 1.2.
 
    * - ,
      - AND
-     - ``>=2,<3`` matches all packages in the 2 series.
-
-       2.0, 2.1, and 2.9 all match, but 3.0 and 1.0 do not.
+     - ``>=2,<3`` matches all packages in the 2 series. 2.0, 2.1, and 2.9 all match, but 3.0 and 1.0 do not.
 
 .. hint::
    ``,`` has higher precedence than \|, so >=1,<2|>3 means greater than or equal to 1 AND less than 2 or greater than 3, which matches 1, 1.3 and 3.0, but not 2.2.
@@ -380,17 +370,17 @@ the following characters: <, >, \*, or \|.
    * - Example
      - Meaning
 
-   * - conda install numpy=1.11
+   * - ``conda install numpy=1.11``
      - The fuzzy constraint numpy=1.11 matches 1.11, 1.11.0, 1.11.1, 1.11.2, 1.11.18, and so on.
 
-   * - conda install numpy==1.11
+   * - ``conda install numpy==1.11``
      - The exact constraint numpy==1.11 matches 1.11, 1.11.0, 1.11.0.0, and so on.
 
-   * - conda install "numpy=1.11.1|1.11.3"
+   * - ``conda install "numpy=1.11.1|1.11.3"``
      - The OR constraint "numpy=1.11.1|1.11.3" matches with 1.11.1 or 1.11.3.
 
-   * - conda install "numpy>1.11"
+   * - ``conda install "numpy>1.11"``
      - Any numpy version 1.12.0a or greater.
 
-   * - conda install "numpy>=1.8,<2"
+   * - ``conda install "numpy>=1.8,<2"``
      - The AND constraint "numpy>=1.8,<2" matches with 1.8 and 1.9 but not 2.0.
diff --git a/docs/source/resources/tutorial-template.rst b/docs/source/resources/tutorial-template.rst
@@ -2,10 +2,6 @@
 Tutorial template
 =================
 
-.. contents::
-   :local:
-   :depth: 1
-
 .. _[email protected]: [email protected]
 
 *This document describes the steps for creating*

diff --git a/docs/source/user-guide/environment-variables.rst b/docs/source/user-guide/environment-variables.rst
@@ -4,10 +4,6 @@
 Environment variables
 =====================
 
-.. contents::
-   :local:
-   :depth: 1
-
 .. _build-state:
 
 Dynamic behavior based on state of build process