Initial reworking of docs

conda · Jul 28, 2023 · 7e0ad83 · 7e0ad83
1 parent e13a319
commit 7e0ad83
Show file tree

Hide file tree

Showing 8 changed files with 224 additions and 211 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -39,6 +39,7 @@
     'sphinx.ext.inheritance_diagram',
     # 'sphinx.ext.napoleon',
     "sphinx_sitemap",
+    "sphinx_design",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/source/create_miniconda_hash_rst.py b/docs/source/create_miniconda_hash_rst.py
@@ -20,7 +20,7 @@
 HASH_LEN = 68
 
 HERE = Path(__file__).parent
-OUT_FILENAME = HERE / "miniconda_hashes.rst"
+OUT_FILENAME = HERE / "miniconda-hashes.rst"
 
 
 def sizeof_fmt(num, suffix="B"):

diff --git a/docs/source/miniconda-install.rst b/docs/source/miniconda-install.rst
@@ -0,0 +1,63 @@
+====================
+Installing Miniconda
+====================
+
+.. tab-set::
+
+    .. tab-item:: Windows graphical installer
+
+        #. `Download the installer. <https://conda.io/miniconda.html>`_
+        #. (Optional) Verify your installer's SHA-256 checksum. This check proves that the installer you downloaded is the original one.
+
+           a. Open PowerShell version 4.0 or later.
+           b. Run the following command, replacing ``filename`` with the path to your installer.
+
+              .. code-block:: powershell 
+
+                 Get-FileHash filename -Algorithm SHA256
+
+           c. Check the hash that appears against the hash listed next to the installer you downloaded. See :doc:`all Miniconda installer hashes here <miniconda-hashes>`.
+
+        #. Double-click the `.exe` file.
+        #. Follow the instructions on the screen. If you are unsure about any setting, accept the defaults. You can change them later.
+        #. When the installation finishes, from the Start menu, open the Anaconda Prompt.
+        #. Test your installation by running ``conda list``. If conda has been installed correctly, a list of installed packages appears.
+
+        `More information on installing in silent mode on Windows is in the conda project documentation <https://conda.io/projects/conda/en/stable/user-guide/install/windows.html>`_.
+
+    .. tab-item:: macOS graphical installer
+
+        #. `Download the installer. <https://conda.io/miniconda.html>`_
+        #. (Optional) Verify your installer's SHA-256 checksum. This check proves that the installer you downloaded is the original one.
+
+           a. Open a terminal application.
+           b. Run the following command, replacing `filename` with the path to your installer.
+
+              .. code-block:: shell
+
+                 shasum -a 256 filename
+
+           c. Check the hash that appears against the hash listed next to the installer you downloaded. See :doc:`all Miniconda installer hashes here <miniconda-hashes>`.
+
+        #. Double-click the `.pkg` file.
+        #. Follow the instructions on the screen. If you are unsure about any setting, accept the defaults. You can change them later.
+        #. When the installation finishes, open your terminal application.
+        #. Test your installation by running ``conda list``. If conda has been installed correctly, a list of installed packages appears.
+
+        `More information on installing in silent mode on macOS is in the conda project documentation <https://conda.io/projects/conda/en/stable/user-guide/install/macos.html>`_.
+
+    .. tab-item:: Linux
+
+        #. Open your terminal.
+        #. Run the following command, replacing `filename` with the path to your installer.
+
+        .. code-block:: shell
+
+           sha256sum filename
+
+For more information on this process (and instructions for using Windows PowerShell 3.0 or older), see the `instructions in the conda project documentation <https://conda.io/projects/conda/en/stable/user-guide/install/download.html#cryptographic-hash-verification>`_.
+
+On Windows, macOS, and Linux, it is best to install Miniconda for the local user,
+which does not require administrator permissions and is the most robust type of
+installation. However, if you need to, you can install Miniconda system wide,
+which does require administrator permissions.
diff --git a/docs/source/miniconda-other-resources.rst b/docs/source/miniconda-other-resources.rst
@@ -0,0 +1,49 @@
+===============
+Other resources
+===============
+
+ -  `Miniconda Docker images <https://hub.docker.com/r/continuumio/>`_
+ -  `Miniconda AWS images <https://aws.amazon.com/marketplace/seller-profile?id=29f81979-a535-4f44-9e9f-6800807ad996>`_
+ -  `Installer and SHA256 hash archive <https://repo.anaconda.com/miniconda/>`_
+ -  `conda release notes <https://conda.io/projects/continuumio-conda/en/latest/release-notes.html>`_
+
+Miniconda's installers contain the conda package manager, Python, and a few necessary packages. Once Miniconda is
+installed, you can use the conda command to install any other packages and create environments.
+
+For example:
+
+ .. container:: highlight-bash notranslate
+
+    .. container:: highlight
+
+       ::
+
+          $ conda install numpy
+          ...
+          $ conda create -n py3k anaconda python=3
+          ...
+
+There are two variants of the installer: Miniconda is Python 2 based, while Miniconda3 is Python 3 based.
+Which Miniconda is installed only affects the root environment. Regardless of which version of Miniconda you
+install, you can still use conda to install both Python 2.x and Python 3.x environments.
+
+However, Miniconda3 (the Python 3 version of Miniconda) will default to Python 3 when creating new environments 
+and building packages.
+
+For example, take the command below:
+
+ .. container:: highlight-bash notranslate
+
+    .. container:: highlight
+
+       ::
+
+          $ conda create -n myenv python
+
+Miniconda (Python 2 based) installs Python 2.7, while Miniconda3 (Python 3 based) installs Python 3.11 by default.
+You can override the default by explicitly setting ``python=2`` or ``python=3`` when creating the environment. The
+Miniconda version also determines the default value of ``CONDA_PY`` when using ``conda build``.
+
+ .. note::
+    If you already have Miniconda or Anaconda installed, and you just want to upgrade, you should
+    not use the installer. Just use ``conda update conda``.
diff --git a/docs/source/miniconda-system-requirements.rst b/docs/source/miniconda-system-requirements.rst
@@ -0,0 +1,15 @@
+===================
+System requirements
+===================
+
+* License: Free use and redistribution under the terms of the `EULA for Miniconda <https://legal.anaconda.com/policies/en?name=offering-specific-terms#miniconda>`_.
+* Operating system: Windows 10 or newer, 64-bit macOS 10.13+, or Linux, including Ubuntu, RedHat, CentOS 7+, and others.
+* If your operating system is older than what is currently supported, you can find older versions of the Miniconda installers in our `archive <https://repo.anaconda.com/miniconda/>`_ that might work for you.
+* System architecture: Windows- 64-bit x86, 32-bit x86; macOS- 64-bit x86 & Apple M1 (ARM64); Linux- 64-bit x86, 64-bit aarch64 (AWS Graviton2), 64-bit IBM Power8/Power9, s390x (Linux on IBM Z & LinuxONE).
+* The ``linux-aarch64`` Miniconda installer requires ``glibc >=2.26`` and thus will **not** work with CentOS 7, Ubuntu 16.04, or Debian 9 ("stretch").
+* Minimum 400 MB disk space to download and install.
+
+On Windows, macOS, and Linux, it is best to install Miniconda for the local user,
+which does not require administrator permissions and is the most robust type of
+installation. However, if you need to, you can install Miniconda system wide,
+which does require administrator permissions.
diff --git a/docs/source/miniconda.rst b/docs/source/miniconda.rst
@@ -6,39 +6,57 @@
 Miniconda
 =========
 
-Miniconda is a free minimal installer for conda. It is a small, bootstrap
-version of Anaconda that includes only conda, Python, the packages they depend
-on, and a small number of other useful packages, including pip, zlib and a
-few others. Use the ``conda install`` command to install 720+ additional conda
-packages from the Anaconda repository.
-
-`See if Miniconda is right for you <https://docs.conda.io/projects/conda/en/stable/user-guide/install/download.html#anaconda-or-miniconda>`_.
-
-System requirements
-===================
-
-* License: Free use and redistribution under the terms of the `EULA for Miniconda <https://legal.anaconda.com/policies/en?name=offering-specific-terms#miniconda>`_.
-* Operating system: Windows 10 or newer, 64-bit macOS 10.13+, or Linux, including Ubuntu, RedHat, CentOS 7+, and others.
-* If your operating system is older than what is currently supported, you can find older versions of the Miniconda installers in our `archive <https://repo.anaconda.com/miniconda/>`_ that might work for you.
-* System architecture: Windows- 64-bit x86, 32-bit x86; macOS- 64-bit x86 & Apple M1 (ARM64); Linux- 64-bit x86, 64-bit aarch64 (AWS Graviton2), 64-bit IBM Power8/Power9, s390x (Linux on IBM Z & LinuxONE).
-* The ``linux-aarch64`` Miniconda installer requires ``glibc >=2.26`` and thus will **not** work with CentOS 7, Ubuntu 16.04, or Debian 9 ("stretch").
-* Minimum 400 MB disk space to download and install.
-
-On Windows, macOS, and Linux, it is best to install Miniconda for the local user,
-which does not require administrator permissions and is the most robust type of
-installation. However, if you need to, you can install Miniconda system wide,
-which does require administrator permissions.
-
-Installing
-==========
-- :doc:`See hashes for all Miniconda installers <../miniconda_hashes>`.
-- `Verify your installation <https://conda.io/projects/conda/en/stable/user-guide/install/download.html#cryptographic-hash-verification>`_.
-- `Installation
-  instructions <https://conda.io/projects/conda/en/stable/user-guide/install/index.html>`__.
+Miniconda is a free minimal installer for conda. It is a small bootstrap version of Anaconda that includes only conda, Python, the packages they 
+both depend on, and a small number of other useful packages (like pip, zlib, and a few others). If you need more packages, use the ``conda install`` 
+command to install from thousands of packages available by default in Anaconda’s public repo, or from other channels, like conda-forge or bioconda.
+
+**Is Miniconda the right conda install for you?** The `Anaconda or Miniconda <https://docs.conda.io/projects/conda/en/stable/user-guide/install/download.html#anaconda-or-miniconda>`_ page lists some reasons why you might 
+want one installation over the other.
+
+Quick command line install
+==========================
+
+.. tab-set::
+
+   .. tab-item:: macOS 
+
+      .. code-block:: bash
+
+         mkdir -p ~/miniconda3
+         curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh ~/miniconda3/miniconda.sh
+         bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
+         rm -rf ~miniconda3/miniconda.sh
+         ~/miniconda3/bin/conda init bash
+         ~/miniconda3/bin/conda init zsh
+
+      If necessary, replace the installer name with the one you want to install.
+
+   .. tab-item:: Linux
+
+      .. code-block:: bash
+
+         mkdir -p ~/miniconda3
+         wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
+         bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
+         rm -rf ~/miniconda3/miniconda.sh
+         ~/miniconda3/bin/conda init bash
+         ~/miniconda3/bin/conda init zsh
+
+      If necessary, replace the installer name with the one you want to install.
+
+.. toctree::
+   :maxdepth: 1
+
+   miniconda-system-requirements
+   miniconda-install
+   miniconda-release-notes
+   miniconda-other-resources
 
 Latest Miniconda Installer Links
 ================================
 
+This list of installers is for the latest release of Python: 3.11.3. For installers for older versions of Python, see the sections below. For an archive of Miniconda versions, see https://repo.anaconda.com/miniconda/.
+
 .. csv-table:: Latest - Conda 23.5.2 Python 3.11.3 released July 13, 2023
    :header: Platform,Name,SHA256 hash
    :widths: 5, 10, 80
@@ -116,80 +134,4 @@ Linux installers
    ,`Miniconda3 Linux-ppc64le 64-bit <https://repo.anaconda.com/miniconda/Miniconda3-py38_23.5.2-0-Linux-ppc64le.sh>`_,74.1 MiB,``6fc3bf00d4fe0c724fab884d93b981acbc22bb8fc41c144df6d2fc080ff80e25``
    ,`Miniconda3 Linux-s390x 64-bit <https://repo.anaconda.com/miniconda/Miniconda3-py38_23.5.2-0-Linux-s390x.sh>`_,85.8 MiB,``b840fd5a8474a3e6831cd50a64eadf73239c6ad7deeebf2c3d3fe366220b2722``
 
-Release Notes
-=============
-- :doc:`Release Notes for Miniconda <../miniconda_release_notes>`
-
-Other resources
-===============
-
- -  `Miniconda Docker
-    images <https://hub.docker.com/r/continuumio/>`__
- -  `Miniconda AWS
-    images <https://aws.amazon.com/marketplace/seller-profile?id=29f81979-a535-4f44-9e9f-6800807ad996>`__
- -  `Archive and SHA256 sums for the
-    installers <https://repo.anaconda.com/miniconda/>`__
- -  `conda change
-    log <https://conda.io/projects/continuumio-conda/en/latest/release-notes.html>`__
-
- These Miniconda installers contain the conda
- package manager and Python. Once Miniconda is
- installed, you can use the conda command to install
- any other packages and create environments, etc.
- For example:
-
- .. container:: highlight-bash notranslate
-
-    .. container:: highlight
-
-       ::
-
-          $ conda install numpy
-          ...
-          $ conda create -n py3k anaconda python=3
-          ...
-
- There are two variants of the installer: Miniconda
- is Python 2 based and Miniconda3 is Python 3 based.
- Note that the choice of which Miniconda is
- installed only affects the root environment.
- Regardless of which version of Miniconda you
- install, you can still install both Python 2.x and
- Python 3.x environments.
-
- The other difference is that the Python 3 version
- of Miniconda will default to Python 3 when creating
- new environments and building packages. So for
- instance, the behavior of:
-
- .. container:: highlight-bash notranslate
-
-    .. container:: highlight
-
-       ::
-
-          $ conda create -n myenv python
-
- will be to install Python 2.7 with the Python 2
- Miniconda and to install Python 3.10 with the Python
- 3 Miniconda. You can override the default by
- explicitly setting ``python=2`` or ``python=3``. It
- also determines the default value of ``CONDA_PY``
- when using ``conda build``.
-
- .. note::
-    If you already have Miniconda or Anaconda
-    installed, and you just want to upgrade, you should
-    not use the installer. Just use ``conda update``.
-
- For instance:
-
- .. container:: highlight-bash notranslate
-
-    .. container:: highlight
-
-       ::
-
-          $ conda update conda
 
- will update conda.