conda · travishathaway · Nov 28, 2023 · Nov 15, 2023 · Nov 28, 2023
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/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/compiler-tools.rst b/docs/source/resources/compiler-tools.rst
@@ -394,6 +394,71 @@ not available. You'd need to create a metapackage ``m2w64-gcc_win-64`` to
 point at the ``m2w64-gcc`` package, which does exist on the msys2 channel on
 `repo.anaconda.com <https://repo.anaconda.com/>`_.
 
+Expressing the relation between compiler and its standard library
+=================================================================
+
+For most languages, certainly for "c" and for "cxx", compiling any given
+program *may* create a run-time dependence on symbols from the respective
+standard library. For example, the standard library for C on linux is generally
+``glibc``, and a core component of your operating system. Conda is not able to
+change or supersede this library (it would be too risky to try to). A similar
+situation exists on MacOS and on Windows.
+
+Compiler packages usually have two ways to deal with this dependence:
+
+* assume the package must be there (like ``glibc`` on linux).
+* always add a run-time requirement on the respective stdlib (e.g. ``libcxx``
+  on MacOS).
+
+However, even if we assume the package must be there, the information about the
+``glibc`` version is still a highly relevant piece of information, which is
+also why it is reflected in the ``__glibc``
+`virtual package <https://docs.conda.io/projects/conda/en/stable/user-guide/tasks/manage-virtual.html>`_.
+
+For example, newer packages may decide over time to increase the lowest version
+of ``glibc`` that they support. We therefore need a way to express this
+dependence in a way that conda will be able to understand, so that (in
+conjunction with the ``__glibc`` virtual package) the environment resolver will
+not consider those packages on machines whose ``glibc`` version is too old.
+
+The way to do this is to use the Jinja2 function ``{{ stdlib('c') }}``, which
+matches ``{{ compiler('c') }}`` in as many ways as possible. Let's start again
+with the ``conda_build_config.yaml``::
+
+    c_stdlib:
+      - sysroot                     # [linux]
+      - macosx_deployment_target    # [osx]
+    c_stdlib_version:
+      - 2.17                        # [linux]
+      - 10.13                       # [osx]
+
+In the recipe we would then use::
+
+    requirements:
+      build:
+        - {{ compiler('c') }}
+        - {{ stdlib('c') }}
+
+This would then express that the resulting package requires ``sysroot ==2.17``
+(corresponds to ``glibc``) on linux and ``macosx_deployment_target ==10.13`` on
+MacOS in the build environment, respectively. How this translates into a
+run-time dependence can be defined in the metadata of the respective conda
+(meta-)package which represents the standard library (i.e. those defined under
+``c_stdlib`` above).
+
+In this example, ``sysroot 2.17`` would generate a run-export on
+``__glibc >=2.17`` and ``macosx_deployment_target 10.13`` would similarly
+generate ``__osx >=10.13``. This way, we enable packages to define their own
+expectations about the standard library in a unified way, and without
+implicitly depending on some global assumption about what the lower version
+on a given platform must be.
+
+In principle, this facility would make it possible to also express the
+dependence on separate stdlib implementations (like ``musl`` instead of
+``glibc``), or to remove the need to assume that a C++ compiler always needs to
+add a run-export on the C++ stdlib -- it could then be left up to packages
+themselves whether they need ``{{ stdlib('cxx') }}`` or not.
+
 Anaconda compilers implicitly add RPATH pointing to the conda environment
 =========================================================================
 

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:
 
@@ -1928,10 +1923,10 @@ variables are booleans.
    * - osx
      - True if the platform is macOS.
    * - arm64
-     - True if the platform is macOS and the Python architecture
-       is arm64.
+     - True if the platform is either macOS or Windows and the
+       Python architecture is arm64.
    * - unix
-     - True if the platform is either macOS or Linux.
+     - True if the platform is either macOS or Linux or emscripten.
    * - win
      - True if the platform is Windows.
    * - win32
@@ -1965,6 +1960,11 @@ The use of the Python version selectors, `py27`, `py34`, etc. is discouraged in
 favor of the more general comparison operators.  Additional selectors in this
 series will not be added to conda-build.
 
+Note that for each subdir with OS and architecture that `conda` supports,
+two preprocessing selectors are created for the OS and the architecture separately
+except when the architecture is not a valid python expression (`*-32` and `*-64`
+in particular).
+
 Because the selector is any valid Python expression, complicated
 logic is possible:
 

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