Clean up docs

docs/advanced_usage.rst

@@ -143,7 +143,7 @@ The *recommended* method to explicitly activate your environment when using
 
    docker exec <container> micromamba run -n <environment_name> <command>
 
-If you want to use the base environment, you can omit ``-n <environment_name>``.
+If you want to use the ``base`` environment, you can omit ``-n <environment_name>``.
 
 An alternative method to trigger activation is to explicitly run your command
 within an interactive ``bash`` shell with ``-i``:

docs/development.rst

@@ -68,22 +68,34 @@ is not found on the ``$PATH``.
 Road map
 --------
 
-The current road map for expanding the number of base images and supported
-shells is as follows:
+Community members are welcomed and encouraged to propose development
+work that supports their needs.
 
-#. Add non-Debian based distributions that have community interest
+The image maintainers are currently working on or planning to work on:
+
+#. Adding non-Debian based distributions that have community interest
 
    * Add ``public.ecr.aws/amazonlinux/amazonlinux:2023`` as a base image
 
-#. Add support for non-``bash`` shells based on community interest
+#. Better supporting conda environment activation when using
+   ``apptainer``/``singularity``
 
-The build and test infrastructure will need to be altered to support additional
-base images such that automated test and build occur for all images produced.
+#. Improved caching during our image builds such that image digests only are
+   modified by pull requests that alter the image. Documentation changes
+   should not result in new image digests.
 
 Policies
 --------
 
+#. No additional programs or packages are installed into the parent images
+   except for those required by ``micromamba``, our helper scripts, and 
+   ``glibc`` (as conda packges generally have a dependency on ``glibc``).
+   We aim to keep our images small and limit our dependencies.
+
 #. Entrypoint script should not write to files in the home directory. On some
-   container execution systems, the host home directory is automatically
-   mounted and we don't want to mess up or pollute the home directory on the
-   host system.
+   container execution systems, such as ``appatainer``, the host home
+   directory is automatically mounted and we don't want to mess up or pollute
+   the home directory on the host system.
+
+#. We do not update any packages within the parent images (ie, we do not
+   ``apt-get update`` or similar).

docs/faq.rst

@@ -13,7 +13,7 @@ This can happen if you forgot to include a channel that is the source for a
 required package.
 
 This error sometimes occurs when moving from one CPU architecture to another,
-such as when moving from x86 to a ARM-based CPUs (such as Apple M1 and M2 CPUs).
+such as when moving from x86 to ARM-based CPUs (such as Apple M1 and M2 CPUs).
 Some conda repositories do a good job of supporting multiple architectures
 (such as Conda Forge), but others only support x86 CPUs (Bioconda). You can
 work around this by forcing ``docker build ...`` to emulate another CPU

docs/quick_start.rst

@@ -1,12 +1,13 @@
 Quick Start
 ===========
 
-The micromamba image comes with an empty environment named ``base``. Usually you
-will install software into this ``base`` environment. The
-``mambaorg/micromamba`` image includes any programs from its parent image, the
-``micromamba`` binary, and SSL certificates. ``micromamba`` does not have a
-``python`` dependency, and therefore the ``mambaorg/micromamba`` image does not
-include ``python``.
+The ``mambaorg/micromamba`` images contain only the programs from their parent
+image, the ``micromamba`` binary, ``bash``, SSL certificates, and ``glibc``.
+``micromamba`` does not have a ``python`` dependency, and therefore the
+``mambaorg/micromamba`` images do not contain ``python``.
+
+The micromamba images have an empty conda environment named ``base``. Usually
+you will install software into this ``base`` environment.
 
 #. Define your desired conda environment in a yaml file
 
@@ -20,7 +21,6 @@ include ``python``.
       must use a different environment name, then read the :ref:`documentation
       on multiple environments <multiple-environments>`.
 
-
 #. Copy the yaml file into your docker image and then pass the yaml file as a
    parameter to ``micromamba`` via the ``--file`` switch
 
@@ -46,9 +46,10 @@ include ``python``.
 Running commands in Dockerfile within the conda environment
 -----------------------------------------------------------
 
-While the conda environment is automatically activated for ``docker run ...``
-commands, it is not automatically activated during build. To ``RUN`` a command
-from a conda environment within a Dockerfile, as explained in detail in the
+The conda environment is automatically activated for ``docker run ...``
+commands, but it is not automatically activated during the build of an image
+(``docker build ...``). In order to use a ``RUN`` command to execute a program
+from a conda environment within a ``Dockerfile``, as explained in detail in the
 next two subsections, you *must*:
 
 #. Set ``ARG MAMBA_DOCKERFILE_ACTIVATE=1`` to activate the conda environment
@@ -59,8 +60,9 @@ Activating a conda environment for ``RUN`` commands
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 No conda environment is automatically activated during the execution
-of ``RUN`` commands within a Dockerfile. To have an environment active during
-a ``RUN`` command, you must set ``ARG MAMBA_DOCKERFILE_ACTIVATE=1``. For example:
+of ``RUN`` commands within a ``Dockerfile``. To have an environment active
+during a ``RUN`` command, you must set ``ARG MAMBA_DOCKERFILE_ACTIVATE=1``.
+For example:
 
    .. literalinclude:: ../examples/run_activate/Dockerfile
 
@@ -85,7 +87,7 @@ the context of a conda environment.
 Activating a conda environment for ``ENTRYPOINT`` commands
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The Dockerfile for building the ``mambaorg/micromamba`` image contains:
+The ``Dockerfile`` for building the ``mambaorg/micromamba`` images contains:
 
    .. code-block::
 

docs/shells.rst

@@ -1,5 +1,8 @@
 Supported Shells
 ================
 
-We have been focused on supporting use of the ``bash`` shell. Support for
-additional shells is on our :ref:`road-map-label`.
+Currently we only support the ``bash`` shell.
+
+We will consider supporting other shells if there is substantial community
+interest or a pull request. But thus far interest in other shells has been
+very limited.

pyproject.toml

@@ -4,7 +4,6 @@ line-length = 110
 [[tool.mypy.overrides]]
 module = [
     "nox.*",
-    "semver.*",   # remove after moving to semver 3.x as it supports typing
 ]
 ignore_missing_imports = true