more docs touch ups

Author: tclose

new-docs/source/conf.py

@@ -155,7 +155,7 @@
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = "Pydra v{}".format(__version__)
+html_title = "Pydra v{}".format(version)
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 # html_short_title = 'Pydra v<release>'

new-docs/source/explanation/typing.rst

@@ -30,11 +30,11 @@ more generic ``fileformats.generic.FsObject`` or ``fileformats.generic.FileSet``
 
 The only cases where it isn't sufficient to use generic classes, is when there are
 implicit header or side cars assumed to be present adjacent to the primary file (e.g.
-a NIfTI file with an associated JSON sidecar file). Because in these cases, the
-header/sidecar file(s) will not be included in the hash calculation and may not be included in the
-movement of the "file set" between working directories. In these cases, you need to use the
-specific file format classes, such as ``fileformats.nifti.NiftiGzX``, which will check
-to see if the header/sidecar files are present.
+a NIfTI file `my_nifti.nii` with an associated JSON sidecar file `my_nifti.json`).
+Because the header/sidecar file(s) will not be included in the hash calculation
+by default and may be omitted if the "file set" is copied into a different work
+directories. In such cases, a specific file format class, such as
+``fileformats.nifti.NiftiGzX``, should be used instead.
 
 Coercion
 --------

new-docs/source/index.rst

@@ -3,25 +3,24 @@
 Pydra
 =====
 
-Pydra is a lightweight, Python 3.11+ dataflow engine for computational graph construction,
-manipulation, and distributed execution. Designed as a successor to Nipype_,
-Pydra is a general-purpose engine that supports analytics in any scientific domain.
-Pydra helps build reproducible, scalable, reusable scientific workflows
-that combine Python functions and shell commands.
+Pydra is a lightweight Python dataflow engine for scientific analysis.
+Although designed as a successor to Nipype_, Pydra is supports analytics in any domain.
+Pydra helps build reproducible, scalable, reusable workflows that link processing tasks
+implemented in Python or shell commands to be executed on distributed compute platforms.
 
-The power of Pydra lies in ease of constructing workflows, containing complex
-multiparameter map-reduce operations, in Python code and the use of a global cache (see
-:ref:`Design philosophy` for the rationale behind its design).
+The power of Pydra lies in ease of constructing workflows containing complex
+multiparameter map-reduce operations in Python code (see :ref:`Design philosophy` for
+the rationale behind its design).
 
-**Key features**:
+**Key features:**
 
 * Combine diverse tasks (`Python functions <./tutorial/3-python.html>`__ or `shell commands <./tutorial/4-shell.html>`__) into coherent `workflows <./tutorial/5-workflow.html>`__
-* Map-reduce like semantics (see :ref:`Splitting and combining`)
+* Concurrent execution on `choice of computing platform (e.g. workstation, SLURM, SGE, Dask, etc...) <./tutorial/2-advanced-execution.html#Workers>`__
 * Dynamic workflow construction using Python code (see :ref:`Dynamic construction`)
-* Modular backends for deployment on different execution platforms (e.g. cloud, HPC, etc...) (see `Execution options <./tutorial/2-advanced-execution.html>`__)
-* Support for the execution of tasks in containerized environments (see :ref:`Software environments`)
+* Map-reduce-like semantics (see :ref:`Splitting and combining`)
 * Global caching to reduce recomputation (see :ref:`Caches and hashes`)
-* Support for strong type-checking, including file types, at workflow construction time (see :ref:`Typing and file-formats`)
+* Tasks can be executed in separate software environments, e.g. containers (see :ref:`Software environments`)
+* Strong type-checking, including file types, before execution (see :ref:`Typing and file-formats`)
 
 
 Installation
@@ -32,21 +31,20 @@ therefore, it is straightforward to install via pip for Python >= 3.11
 
 .. code-block:: bash
 
-    $ pip install pydra
+   $ pip install pydra
 
 Pre-designed tasks are available under the `pydra.tasks.*` package namespace. These tasks
-are implemented within separate packages that are typically specific to a given shell-command toolkit such as FSL_, AFNI_ or ANTs_,
-or a collection of related tasks/workflows (e.g. `niworkflows`_). Pip can be used to
-install these packages as well:
-
+are implemented within separate packages that are typically specific to a given
+shell-command toolkit such as FSL_, AFNI_ or ANTs_, or a collection of related
+tasks/workflows (e.g. `niworkflows`_). Pip can be used to install these packages as well:
 
 .. code-block:: bash
 
-    $ pip install pydra-fsl pydra-ants
+   $ pip install pydra-fsl pydra-ants
 
-Of course, if you use Pydra to execute commands within toolkits, you will need to
-either have those commands installed on the execution machine, or use containers
-environments (see `Environments <../explanation/environments.html>`__) to run them.
+Of course, if you use Pydra to execute commands within non-Python toolkits, you will
+need to either have those commands installed on the execution machine, or use containers
+to run them (see :ref:`Software environments`).
 
 
 Tutorials and notebooks
@@ -55,10 +53,14 @@ Tutorials and notebooks
 The following tutorials provide a step-by-step guide to using Pydra.
 They can be read in any order, but it is recommended to start with :ref:`Getting started`.
 The tutorials are implemented as Jupyter notebooks, which can be downloaded and run locally
-or run online using the |Binder| within each tutorial.
+or run online using the |Binder| button within each tutorial.
 
 If you decide to download the notebooks and run locally, be sure to install the necessary
-dependencies with ``pip install -e /path/to/your/pydra[tutorial]``.
+dependencies with
+
+.. code-block:: bash
+
+   $ pip install -e /path/to/your/pydra[tutorial]
 
 
 Execution
@@ -67,7 +69,7 @@ Execution
 Learn how to execute existing tasks (including workflows) on different systems
 
 * :ref:`Getting started`
-* :ref:`Execution options`
+* :ref:`Advanced execution`
 
 Design
 ~~~~~~