updated heading style

Author: preminger

appendix.rst

@@ -1,17 +1,17 @@
 .. _appendix:
 
-##########
- Appendix
-##########
+########
+Appendix
+########
 
 ..
    TODO oci & oci-archive along with http & https
 
 .. _singularity-environment-variables:
 
-***************************************
- {Singularity}'s environment variables
-***************************************
+*************************************
+{Singularity}'s environment variables
+*************************************
 
 {Singularity} 3.0 comes with some environment variables you can set or
 modify depending on your needs. You can see them listed alphabetically
@@ -400,9 +400,9 @@ below with their respective functionality.
 
 .. _buildmodules:
 
-***************
- Build Modules
-***************
+*************
+Build Modules
+*************
 
 .. _build-library-module:
 
@@ -989,7 +989,7 @@ The ``SINGULARITY_DOCKER_HOST`` or ``DOCKER_HOST`` environment variables may be
 set to instruct {{Singularity}} to pull images from a Docker daemon that is not
 running at the default location. For example, when using a virtualized Docker you may be instructed to set ``DOCKER_HOST`` e.g.
 
-.. code:: 
+.. code::
 
    To connect the Docker client to the Docker daemon, please set
    export DOCKER_HOST=tcp://192.168.59.103:2375

bind_paths_and_mounts.rst

@@ -1,8 +1,8 @@
 .. _bind-paths-and-mounts:
 
-#######################
- Bind Paths and Mounts
-#######################
+#####################
+Bind Paths and Mounts
+#####################
 
 .. _sec:bindpaths:
 
@@ -12,9 +12,9 @@ Unless `disabled by the system administrator
 directories within your container using bind mounts. This allows you to
 read and write data on the host system with ease.
 
-**********
- Overview
-**********
+********
+Overview
+********
 
 When {Singularity} ‘swaps’ the host operating system for the one inside
 your container, the host file systems becomes inaccessible. However, you
@@ -23,9 +23,9 @@ container. To enable this functionality, {Singularity} will bind
 directories back into the container via two primary methods:
 system-defined bind paths and user-defined bind paths.
 
-***************************
- System-defined bind paths
-***************************
+*************************
+System-defined bind paths
+*************************
 
 The system administrator has the ability to define what bind paths will
 be included automatically inside each container. Some bind paths are
@@ -82,9 +82,9 @@ To disable all ``bind path`` entries set in ``singularity.conf``, use
 
 .. _user-defined-bind-paths:
 
-*************************
- User-defined bind paths
-*************************
+***********************
+User-defined bind paths
+***********************
 
 Unless the system administrator has `disabled user control of binds
 <https://singularity-admindoc.readthedocs.io/en/latest/the_singularity_config_file.html#user-bind-control-boolean-default-yes>`_,
@@ -266,9 +266,9 @@ host ``$HOME`` directory with the ``--no-home`` flag.
 
    $ singularity shell --containall my_container.sif
 
-*************
- FUSE mounts
-*************
+***********
+FUSE mounts
+***********
 
 Filesystem in Userspace (FUSE) is an interface to allow filesystems to
 be mounted using code that runs in userspace, rather than in the Linux
@@ -373,9 +373,9 @@ added to your container, you can use the ``container`` mount type:
    Singularity> cat /server/etc/hostname
    server
 
-**************
- Image Mounts
-**************
+************
+Image Mounts
+************
 
 In {Singularity} 3.6 and above you can mount a directory contained in an
 image file into a container. This may be useful if you want to

build_env.rst

@@ -1,14 +1,14 @@
 .. _build-environment:
 
-###################
- Build Environment
-###################
+#################
+Build Environment
+#################
 
 .. _sec:buildenv:
 
-**********
- Overview
-**********
+********
+Overview
+********
 
 You may wish to customize your build environment by doing things such as
 specifying a custom cache directory for images or sending your Docker
@@ -17,9 +17,9 @@ other topics related to the build environment.
 
 .. _sec:cache:
 
-***************
- Cache Folders
-***************
+*************
+Cache Folders
+*************
 
 {Singularity} will cache SIF container images generated from remote
 sources, and any OCI/docker layers used to create them. The cache is
@@ -102,9 +102,9 @@ file:
 
    rm ~/.local/share/containers/cache/blob-info-cache-v1.boltdb
 
-****************
- Cache commands
-****************
+**************
+Cache commands
+**************
 
 The ``cache`` command for {Singularity} allows you to view and clean up
 your cache, without manually inspecting the cache directories.
@@ -212,9 +212,9 @@ use the ``type`` / ``-T`` option:
 
 .. _sec:temporaryfolders:
 
-*******************
- Temporary Folders
-*******************
+*****************
+Temporary Folders
+*****************
 
 When building a container, or pulling/running a {Singularity} container
 from a Docker/OCI source, a temporary working space is required. The
@@ -250,19 +250,19 @@ Remember to use ``-E`` option to pass the value of
    Set ``SINGULARITY_TMPDIR`` to a disk location, or disable the
    ``tmpfs`` ``/tmp`` mount on your system if you experience problems.
 
-**********************
- Encrypted Containers
-**********************
+********************
+Encrypted Containers
+********************
 
 Beginning in {Singularity} 3.4.0 it is possible to build and run
 encrypted containers. The containers are decrypted at runtime entirely
 in kernel space, meaning that no intermediate decrypted data is ever
 present on disk or in memory. See :ref:`encrypted containers
 <encryption>` for more details.
 
-***********************
- Environment Variables
-***********************
+*********************
+Environment Variables
+*********************
 
 #. If a flag is represented by both a CLI option and an environment
    variable, and both are set, the CLI option will always take

cgroups.rst

@@ -1,8 +1,8 @@
 .. _cgroups:
 
-##############################
- Limiting Container Resources
-##############################
+############################
+Limiting Container Resources
+############################
 
 It's often useful to limit the resources that are consumed by a container, e.g.
 to allow the container to only use 1 CPU, or 50% of the RAM on the system.
@@ -23,16 +23,16 @@ There are three ways to apply limits to a container that is run with
 {Singularity}:
 
 * Using the command line flags introduced in v3.10.
- 
+
 * Using the ``--apply-cgroups`` flag to apply a ``cgroups.toml`` file that
   defines the resource limits.
 
 * Using external tools such as ``systemd-run`` tool to apply limits, and then
   call ``singularity``.
 
-******************************
- Requirements - Linux Cgroups
-******************************
+****************************
+Requirements - Linux Cgroups
+****************************
 
 Resource limits are applied to containers using functionality in the Linux
 kernel known as *control groups* or *cgroups*. There are two versions of
@@ -63,9 +63,9 @@ about this.
 
 .. _cgroup_flags:
 
-***************************
- Command Line Limit Flags
-***************************
+*************************
+Command Line Limit Flags
+*************************
 
 {Singularity} 3.10 introduced a number of simple command line flags that you can
 use with `shell/run/exec` and the `instance` commands to directly apply resource
@@ -88,7 +88,7 @@ use.  The minimum is ``0.01`` or one tenth of a physical CPU. The maximum is the
 number of CPU cores on your system.
 
 .. code::
-   
+
    # Limit container to 3.5 CPUs
    $ singularity run --cpus 3.5 myfirstapp.sif
 
@@ -100,7 +100,7 @@ there is contention for CPUs*, i.e. the containers are able to consume more CPU
 time than is available.
 
 .. code::
-   
+
    # Container A - twice as much CPU priority as container B
    $ singularity run --cpu-shares 1024 myfirstapp.sif
 
@@ -115,7 +115,7 @@ run. For example, on a dual CPU system you might pin one container to the first
 should generally be set to the same value as ``--cpu-set-cpus``.
 
 .. code::
-   
+
    # Container A - first CPU
    $ singularity run --cpu-set-cpus 0-11 --cpu-set-mems 0-11 myfirstapp.sif
 
@@ -130,7 +130,7 @@ You can use suffixes such as ``M`` or ``G`` to specify megabytes or gigabytes.
 If the container tries to use more memory than its limit, the system will kill
 it.
 
-.. code:: 
+.. code::
 
    # Run a program that will use 10GB of RAM, with a 100MB limit
    $ singularity exec --memory 100M memhog.sif memhog 10G
@@ -140,7 +140,7 @@ it.
 limit set with ``--memory``. When there is contention for memory, the system
 will attempt to make sure the container doesn't exceed the soft limit.
 
-.. code:: 
+.. code::
 
    # Kill my program if it exceeds 10G, but aim for 8G if there is contention
    $ singularity exec --memory 10G --memory-reservation 8G myfirstapp.sif
@@ -169,7 +169,7 @@ value of ``-1`` means *unlimited swap*. If ``--memory-swap`` is not set or is
 IO Limits
 =========
 
-.. note:: 
+.. note::
 
    Requires the ``cfq`` or ``bfq`` IO scheduler to be configured for block IO on
    the system. This is common on modern distributions, but not universal. Ask
@@ -182,7 +182,7 @@ is contention for I/O with other containers. It may be useful to give high
 priority to a container that needs infrequent but time sensitive data access,
 running alongside an application that is continuously performing bulk reads.
 
-.. code:: 
+.. code::
 
    # Container A - ten times as much block IO priority as container B
    $ singularity run --blkio-weight 1000 myfirstapp.sif
@@ -193,17 +193,17 @@ running alongside an application that is continuously performing bulk reads.
 ``--blkio-weight-device`` sets a relative weight for the container when performing
 block I/O on a specific device. Specify the device and weight as ``<device path>:weight``:
 
-.. code:: 
+.. code::
 
    # Container A - ten times as much block IO priority as container B on disk /dev/sda
    $ singularity run --blkio-weight-device /dev/sda:1000 myfirstapp.sif
 
    # Container A - ten times less block IO priority as container A on disk /dev/sda
    $ singularity run --blkio-weight-device /dev/sda:100 mysecondapp.sif
 
-********************************************
- Applying Resource Limits From a TOML file
-********************************************
+******************************************
+Applying Resource Limits From a TOML file
+******************************************
 
 {Singularity} 3.9 and above can directly apply resource limitations to systems
 configured for both cgroups v1 and the v2 unified hierarchy, using the
@@ -227,7 +227,7 @@ configuration to be applied:
 
    $ singularity shell --apply-cgroups /path/to/cgroups.toml my_container.sif
 
-.. note:: 
+.. note::
 
    Using ``--apply-cgroups`` as a non-root user requires a cgroups v2 system,
    configured to use the ``systemd cgroups`` manager in ``singularity.conf``.
@@ -379,7 +379,7 @@ is specified in bytes per second.
 Device Limits
 =============
 
-.. note:: 
+.. note::
 
    Device limits can only be applied when running as the root user, and will be
    ignored as a non-root user.
@@ -417,9 +417,9 @@ https://github.com/opencontainers/runtime-spec/blob/master/config-linux.md#contr
 for information about the available limits. Note that {Singularity} uses
 TOML format for the configuration file, rather than JSON.
 
-**********************************************
- Applying Resource Limits With External Tools
-**********************************************
+********************************************
+Applying Resource Limits With External Tools
+********************************************
 
 Because {Singularity} starts a container as a simple process, rather
 than using a daemon, you can limit resource usage by running the

cli.rst

@@ -1,8 +1,8 @@
 .. _cli:
 
-########################
- Command Line Interface
-########################
+######################
+Command Line Interface
+######################
 
 Below are links to the automatically generated CLI docs