User guide refactors and updates (conda#13454)

Co-authored-by: Katherine Kinnaman <[email protected]> Co-authored-by: Jannis Leidel <[email protected]> Co-authored-by: Bianca Henderson <[email protected]>
afloren · Jan 11, 2024 · 10c50c4 · 10c50c4
1 parent 2ce6a14
commit 10c50c4
Show file tree

Hide file tree

Showing 33 changed files with 1,485 additions and 1,413 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -218,6 +218,9 @@ def setup(sphinx):
     "using/pkgs": "../user-guide/tasks/manage-pkgs.html",
     "using/test-drive": "../user-guide/getting-started.html",
     "using/using": "../user-guide/tasks/manage-conda.html",
+    "user-guide/install/download": "../install/index.html",
+    "user-guide/configuration/sample-condarc": "../configuration/use-condarc.html#sample-condarc",
+    "user-guide/configuration/enable-tab-completion": "../configuration/index.html",
     # external redirects
     "travis": "https://github.com/conda-incubator/setup-miniconda",
     "user-guide/tasks/use-conda-with-travis-ci": "https://github.com/conda-incubator/setup-miniconda",

diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
@@ -153,7 +153,7 @@ packages that are easily installed locally with the
 
 * The Navigator GUI
 
-* A terminal or Anaconda Prompt using conda commands
+* A terminal using conda commands
 
 *  https://repo.anaconda.com/pkgs/
 

diff --git a/docs/source/user-guide/concepts/channels.rst b/docs/source/user-guide/concepts/channels.rst
@@ -1,13 +1,13 @@
-==============
-Conda channels
-==============
+========
+Channels
+========
 
 .. _concepts-channels:
 
-What is a "conda channel"?
-==========================
+What is a "channel"?
+====================
 
-Conda channels are the locations where packages are stored.
+Channels are the locations where packages are stored.
 They serve as the base for hosting and managing packages.
 Conda :doc:`packages <../concepts/packages>` are downloaded
 from remote channels, which are URLs to directories

diff --git a/docs/source/user-guide/concepts/conda-commands.rst b/docs/source/user-guide/concepts/conda-commands.rst
@@ -1,6 +1,6 @@
-==============
-Conda commands
-==============
+========
+Commands
+========
 
 The ``conda`` command is the primary interface for managing
 installations of various packages. It can:

diff --git a/docs/source/user-guide/concepts/conda-performance.rst b/docs/source/user-guide/concepts/conda-performance.rst
@@ -1,6 +1,6 @@
-=================
-Conda performance
-=================
+===========
+Performance
+===========
 
 Conda's performance can be affected by a variety of things.
 Unlike many package managers, Anaconda’s repositories generally

diff --git a/docs/source/user-guide/concepts/conda-plugins.rst b/docs/source/user-guide/concepts/conda-plugins.rst
@@ -1,6 +1,6 @@
-=============
-Conda plugins
-=============
+=======
+Plugins
+=======
 
 .. _concept-plugins:
 

diff --git a/docs/source/user-guide/concepts/environments.rst b/docs/source/user-guide/concepts/environments.rst
@@ -1,11 +1,11 @@
 .. _concepts-conda-environments:
 
-==================
-Conda environments
-==================
+============
+Environments
+============
 
-A conda environment is a directory that contains a specific
-collection of conda packages that you have installed. For
+An environment is a directory that contains a specific
+collection of packages that you have installed. For
 example, you may have one environment with NumPy 1.7 and its
 dependencies, and another environment with NumPy 1.6 for legacy
 testing. If you change one environment, your other environments

diff --git a/docs/source/user-guide/concepts/index.rst b/docs/source/user-guide/concepts/index.rst
@@ -2,10 +2,9 @@
 Concepts
 ========
 
-Explore the links to learn more about conda foundations.
-
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
    conda-commands
    packages
@@ -18,4 +17,37 @@ Explore the links to learn more about conda foundations.
    data-science
    conda-plugins
 
-When you're comfortable with the conda concepts, learn how to :doc:`get started using conda <../getting-started>`.
+In this section, we provide you with detailed information about the fundamental concepts
+in conda, including information about packages, channels, environments, and plugins, among others.
+
+.. glossary::
+
+    :doc:`Commands <conda-commands>`
+        Conda commands are your interface for interacting with everything
+
+    :doc:`Packages <packages>`
+        Learn about the different forms a package can take
+
+    :doc:`Package specification <pkg-specs>`
+        Learn about exactly what belongs in a package and what the different metadata files mean
+
+    :doc:`Package search and install <pkg-search>`
+        The search specifications for a package (for the ``conda install`` and ``conda search`` commands)
+
+    :doc:`Channels <channels>`
+        Learn about channels and how they host packages
+
+    :doc:`Environments <environments>`
+        Learn about how environments work and how they differ from Python's virtual environments
+
+    :doc:`Installing with conda <installing-with-conda>`
+        Take a deep dive into exactly what happens during an installation with conda
+
+    :doc:`Performance <conda-performance>`
+        Understand what impacts the performance and speed of conda and how to improve it
+
+    :doc:`Conda for data scientists <data-science>`
+        See why conda is a such a valuable tool for data scientists
+
+    :doc:`Plugins <conda-plugins>`
+        The behavior of conda can be extended via plugins; learn more here
diff --git a/docs/source/user-guide/concepts/packages.rst b/docs/source/user-guide/concepts/packages.rst
@@ -1,14 +1,14 @@
-==============
-Conda packages
-==============
+========
+Packages
+========
 
 .. _concept-conda-package:
 
-What is a conda package?
-========================
+What is a package?
+==================
 
-A conda package is a compressed tarball file (.tar.bz2) or
-.conda file that contains:
+A package is a compressed tarball file (``.tar.bz2``) or
+``.conda`` file that contains:
 
 * system-level libraries.
 * Python or other modules.
@@ -334,6 +334,6 @@ and unlink steps. For more information, see `Adding pre-link, post-link, and pre
 More information
 ================
 
-Go deeper on how to :ref:`manage packages <managing-pkgs>`.
+For more information, go for a deeper dive in our :doc:`managing packages guide <../tasks/manage-pkgs>`.
 Learn more about package metadata, repository structure and index,
 and package match specifications at :doc:`Package specifications <../concepts/pkg-specs>`.
diff --git a/docs/source/user-guide/concepts/pkg-specs.rst b/docs/source/user-guide/concepts/pkg-specs.rst
@@ -1,6 +1,6 @@
-===========================
-Conda package specification
-===========================
+=====================
+Package specification
+=====================
 
 .. _package_metadata:
 

diff --git a/docs/source/user-guide/configuration/admin-multi-user-install.rst b/docs/source/user-guide/configuration/admin-multi-user-install.rst
@@ -2,11 +2,9 @@
 Administering a multi-user conda installation
 =============================================
 
-By default, conda and all packages it installs, including
-Anaconda, are installed locally with a user-specific
-configuration. Administrative privileges are not required, and
-no upstream files or other users are affected by
-the installation.
+By default, conda and all of the packages it installs are installed locally with a
+user-specific configuration. Administrative privileges are not required, and
+no upstream files or other users are affected by the installation.
 
 You can make conda and any number of packages available to a
 group of one or more users, while preventing these users

diff --git a/docs/source/user-guide/configuration/enable-tab-completion.rst b/docs/source/user-guide/configuration/enable-tab-completion.rst
diff --git a/docs/source/user-guide/configuration/index.rst b/docs/source/user-guide/configuration/index.rst
@@ -4,13 +4,44 @@ Configuration
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
    use-condarc
-   sample-condarc
-   free-channel
+   settings
    admin-multi-user-install
-   enable-tab-completion
-   pip-interoperability
+   mirroring
    disable-ssl-verification
    non-standard-certs
-   mirroring
+   pip-interoperability
+   free-channel
+
+The following pages have information on how conda can be customized further through
+configuration.
+
+.. glossary::
+
+    :doc:`Using the .condarc conda configuration file <use-condarc>`
+        Learn how to use a settings file (``.condarc``) to override defaults and maintain
+        settings across shell sessions
+
+    :doc:`Settings <settings>`
+        View a list and definition of all the configuration settings that can be used within
+        conda
+
+    :doc:`Administering a multi-user conda installation <admin-multi-user-install>`
+        How to set up conda as a system administrator for use by multiple users
+
+    :doc:`Mirroring channels <mirroring>`
+        Explore how to configure your own channel server mirror with conda
+
+    :doc:`Disable SSL Verification <disable-ssl-verification>`
+        Disabling SSL may be necessary in very limited circumstances; learn how here
+
+    :doc:`Using non-standard certificates <non-standard-certs>`
+        Install and configure non-standard certifications for use with conda
+
+    :doc:`Pip interoperability (experimental) <pip-interoperability>`
+        An experimental feature that makes conda operate better with pip (no longer supported)
+
+    :doc:`Free channel (deprecated) <free-channel>`
+        Explanation of our deprecation of the free channel and how to restore it
diff --git a/docs/source/user-guide/configuration/sample-condarc.rst b/docs/source/user-guide/configuration/sample-condarc.rst