User-guide concepts

docs/source/user-guide/concepts/conda-performance.rst

@@ -17,13 +17,13 @@ packages. At any point along these steps, performance issues may arise.
 
 Conda follows these steps when installing a package:
 
-#. Downloading and processing index metadata
-#. Reducing the index
-#. Expressing the package data and constraints as a SAT problem
-#. Running the solver
-#. Downloading and extracting packages
-#. Verifying package contents
-#. Linking packages from package cache into environments
+#. Downloading and processing index metadata.
+#. Reducing the index.
+#. Expressing the package data and constraints as a SAT problem.
+#. Running the solver.
+#. Downloading and extracting packages.
+#. Verifying package contents.
+#. Linking packages from package cache into environments.
 
 Therefore, if you're experiencing a slowdown, evaluate the following questions
 to identify potential causes:
@@ -36,7 +36,6 @@ to identify potential causes:
 * Are channels interacting in bad ways?
 
 
-
 Improving conda performance
 ===========================
 

docs/source/user-guide/concepts/environments.rst

@@ -70,6 +70,8 @@ built-in venv library, whereas conda has its own notion of virtual
 environments that is lower-level (Python itself is a dependency provided
 in conda environments).
 
+Scroll to the right in the table below.
+
 Some other traits are:
 
 .. list-table::
@@ -82,41 +84,41 @@ Some other traits are:
    * - **Libraries**
      - Statically link, vendor libraries in wheels,
        or use apt/yum/brew/etc.
-     - Install system-level libraries as conda dependencies
+     - Install system-level libraries as conda dependencies.
    * - **System**
-     - Depend on base system install of Python
-     - Python is independent from system
+     - Depend on base system install of Python.
+     - Python is independent from system.
    * - **Extending environment**
-     - Extend environment with pip
-     - Extended environment with conda or pip
+     - Extend environment with pip.
+     - Extended environment with conda or pip.
    * - **Non-Python dependencies**
      -
      - Manages non-Python dependencies (R, Perl,
-       arbitrary executables)
+       arbitrary executables).
    * - **Tracking dependencies**
      -
-     - Tracks binary dependencies explicitly
+     - Tracks binary dependencies explicitly.
 
 |
 
 Why use venv-based virtual environments
 ---------------------------------------
 
-- You prefer their workflow or spec formats
-- You prefer to use the system Python and libraries
+- You prefer their workflow or spec formats.
+- You prefer to use the system Python and libraries.
 - Your project maintainers only publish to PyPI, and
   you prefer packages that come more directly from the
   project maintainers, rather than someone else providing
-  builds based on the same code
+  builds based on the same code.
 
 Why use conda virtual environments?
 -----------------------------------
 
-- You want control over binary compatibility choices
-- You want to utilize newer language standards, such as C++ 17
-- You need libraries beyond what the system Python offers
+- You want control over binary compatibility choices.
+- You want to utilize newer language standards, such as C++ 17.
+- You need libraries beyond what the system Python offers.
 - You want to manage packages from languages other than Python
-  in the same space
+  in the same space.
 
 Workflow differentiators
 ========================

docs/source/user-guide/concepts/installing-with-conda.rst

@@ -25,13 +25,13 @@ Read more about :doc:`conda environments and directory structure <../concepts/en
 
 * When you ``conda install`` a package that exists in a channel and has no dependencies, conda:
 
-  * looks at your configured channels (in priority)
+  * Looks at your configured channels (in priority).
 
-  * reaches out to the repodata associated with your channels/platform
+  * Reaches out to the repodata associated with your channels/platform.
 
-  * parses repodata to search for the package
+  * Parses repodata to search for the package.
 
-  * once the package is found, conda pulls it down and installs
+  * Once the package is found, conda pulls it down and installs.
 
 Conda update versus conda install
 =================================

docs/source/user-guide/concepts/packages.rst

@@ -14,11 +14,11 @@ What is a conda package?
 A conda package is a compressed tarball file (.tar.bz2) or
 .conda file that contains:
 
-* system-level libraries
-* Python or other modules
-* executable programs and other components
-* metadata under the ``info/`` directory
-* a collection of files that are installed directly into an ``install`` prefix
+* system-level libraries.
+* Python or other modules.
+* executable programs and other components.
+* metadata under the ``info/`` directory.
+* a collection of files that are installed directly into an ``install`` prefix.
 
 Conda keeps track of the dependencies between packages and platforms.
 The conda package format is identical across platforms and
@@ -36,7 +36,7 @@ The .conda file format was introduced in conda 4.7 as a more
 compact, and thus faster, alternative to a tarball.
 
 The .conda file format consists of an outer, uncompressed
-ZIP-format container, with two inner compressed .tar files.
+ZIP-format container, with 2 inner compressed .tar files.
 
 For the .conda format's initial internal compression format support,
 we chose Zstandard (zstd). The actual compression format used does not
@@ -76,7 +76,7 @@ Using packages
   conda install scipy
 
 
-* You may build a package after `installing conda build <https://docs.conda.io/projects/conda-build/en/latest/index.html>`_
+* You may build a package after `installing conda-build <https://docs.conda.io/projects/conda-build/en/latest/index.html>`_
 
 .. code-block:: bash
 
@@ -101,11 +101,11 @@ Package structure
   └── lib
       └── python3.5
 
-* bin contains relevant binaries for the package
+* bin contains relevant binaries for the package.
 
-* lib contains the relevant library files (eg. the .py files)
+* lib contains the relevant library files (eg. the .py files).
 
-* info contains package metadata
+* info contains package metadata.
 
 
 .. _meta-package:
@@ -273,7 +273,7 @@ distribute docs, datasets, and source code in conda packages.
 Noarch Python packages are described below.
 
 Declaring these packages as ``noarch`` in the ``build`` section of
-the meta.yaml reduces shared CI resources. Therefore, all packages
+the ``meta.yaml`` reduces shared CI resources. Therefore, all packages
 that qualify to be noarch packages should be declared as such.
 
 Noarch Python
@@ -289,28 +289,28 @@ at install time.
 In order to qualify as a noarch Python package, all of the following
 criteria must be fulfilled:
 
-* No compiled extensions
+* No compiled extensions.
 
-* No post-link or pre-link or pre-unlink scripts
+* No post-link, pre-link, or pre-unlink scripts.
 
-* No OS-specific build scripts
+* No OS-specific build scripts.
 
-* No python version specific requirements
+* No Python version-specific requirements.
 
 * No skips except for Python version. If the recipe is py3 only,
   remove skip statement and add version constraint on Python in host
   and run section.
 
-* 2to3 is not used
+* 2to3 is not used.
 
-* Scripts argument in setup.py is not used
+* Scripts argument in setup.py is not used.
 
 * If ``console_script`` entrypoints are in setup.py,
-  they are listed in meta.yaml
+  they are listed in ``meta.yaml``.
 
-* No activate scripts
+* No activate scripts.
 
-* Not a dependency of conda
+* Not a dependency of conda.
 
 .. note::
    While ``noarch: python`` does not work with selectors, it does
@@ -319,7 +319,7 @@ criteria must be fulfilled:
    subsections, for example: ``python >=3`` instead of just ``python``.
 
 .. note::
-   Only ``console_script`` entry points have to be listed in meta.yaml.
+   Only ``console_script`` entry points have to be listed in ``meta.yaml``.
    Other entry points do not conflict with ``noarch`` and therefore do
    not require extra treatment.
 

docs/source/user-guide/concepts/pkg-specs.rst

@@ -77,7 +77,7 @@ info/index.json
 This file contains basic information about the package, such as
 name, version, build string, and dependencies. The content of this
 file is stored in ``repodata.json``, which is the repository
-index file, hence the name ``index.json``. The json object is a
+index file, hence the name ``index.json``. The JSON object is a
 dictionary containing the keys shown below. The filename of the
 conda package is composed of the first 3 values, as in:
 ``<name>-<version>-<build>.tar.bz2``. 
@@ -436,12 +436,11 @@ To obtain a predictable version ordering, it is crucial to keep the
 version number scheme of a given package consistent over time.
 Conda considers prerelease versions as less than release versions.
 
-Specifically,
+* Version strings should always have the same number of components
+  (except for an optional tag suffix or local version string).
 
-  * version strings should always have the same number of components
-    (except for an optional tag suffix or local version string),
-  * letters/strings indicating non-release versions should always
-    occur at the same position.
+* Letters/Strings indicating non-release versions should always
+  occur at the same position.
 
 Before comparison, version strings are parsed as follows:
 
@@ -467,12 +466,14 @@ Examples:
 The resulting lists are compared lexicographically, where the following
 rules are applied to each pair of corresponding subcomponents:
 
-  * integers are compared numerically
-  * strings are compared lexicographically, case-insensitive
-  * strings are smaller than integers, except
-  * ``dev`` versions are smaller than all corresponding versions of other types
-  * ``post`` versions are greater than all corresponding versions of other types
-  * if a subcomponent has no correspondent, the missing correspondent is
+  * Integers are compared numerically.
+  * Strings are compared lexicographically, case-insensitive.
+  * Strings are smaller than integers, except
+
+      * ``dev`` versions are smaller than all corresponding versions of other types.
+      
+      * ``post`` versions are greater than all corresponding versions of other types.
+  * If a subcomponent has no correspondent, the missing correspondent is
     treated as integer 0 to ensure ``'1.1' == 1.1.0'``.
 
 The resulting order is::