Document TemplateFlow CLI cache management and API stubs

.gitignore

@@ -73,7 +73,6 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-docs/api/
 
 # PyBuilder
 target/

docs/api/templateflow.api.rst

@@ -0,0 +1,12 @@
+templateflow.api module
+=======================
+
+``templateflow.api`` mirrors the long-standing global helpers while delegating
+all heavy lifting to a shared :class:`templateflow.client.TemplateFlowClient`
+instance.  The directives below document both the public functions and the
+proxied client so that migration guides can reference consistent API signatures.
+
+.. automodule:: templateflow.api
+   :members: get, ls, templates, get_metadata, get_citations, TemplateFlowClient
+   :imported-members:
+   :member-order: bysource

docs/api/templateflow.cli.rst

@@ -0,0 +1,7 @@
+templateflow.cli module
+=======================
+
+.. automodule:: templateflow.cli
+   :members:
+   :undoc-members:
+   :member-order: bysource

docs/api/templateflow.client.rst

@@ -0,0 +1,18 @@
+templateflow.client module
+==========================
+
+The client module provides the object-oriented entry point around the global
+cache described in :mod:`templateflow.conf`.  Its documentation surfaces the
+constructor, cache descriptor, and convenience methods so that downstream code
+can migrate from the module-level API to the richer class interface.
+
+.. automodule:: templateflow.client
+   :members: TemplateFlowClient
+   :undoc-members:
+   :member-order: bysource
+
+.. autoclass:: templateflow.client.TemplateFlowClient
+   :members:
+   :special-members: __init__, __repr__
+   :member-order: bysource
+   :show-inheritance:

docs/api/templateflow.conf.rst

@@ -0,0 +1,22 @@
+templateflow.conf package
+=========================
+
+``templateflow.conf`` centralizes configuration state for both the legacy module
+level helpers (``update``/``wipe``) and the newer :class:`~templateflow.conf.cache.TemplateFlowCache`
+object.  The documentation below highlights the migration path so that users can
+incrementally adopt the cache classes without losing backwards-compatible entry
+points.
+
+.. automodule:: templateflow.conf
+   :members: requires_layout, setup_home, update, wipe
+   :imported-members:
+   :member-order: bysource
+
+Cache management classes
+------------------------
+
+.. automodule:: templateflow.conf.cache
+   :members: CacheConfig, TemplateFlowCache, S3Manager, DataladManager
+   :special-members: __init__
+   :undoc-members:
+   :member-order: bysource

docs/cli.rst

@@ -9,7 +9,66 @@ Examples
 --------
 Listing all the compressed NIfTI files in ``fsaverage``::
 
-	$ templateflow ls fsaverage -x .nii.gz
-	~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_den-41k_T1w.nii.gz
-	~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_desc-brain_mask.nii.gz
-	~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_T1w.nii.gz
+        $ templateflow ls fsaverage -x .nii.gz
+        ~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_den-41k_T1w.nii.gz
+        ~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_desc-brain_mask.nii.gz
+        ~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_T1w.nii.gz
+
+Managing client configuration
+-----------------------------
+The ``templateflow`` CLI transparently manipulates the same cache configuration used
+by :class:`templateflow.client.TemplateFlowClient`.  Running ``templateflow config``
+exposes the options stored in the underlying :class:`templateflow.conf.cache.CacheConfig`
+instance::
+
+        $ templateflow config show
+        TEMPLATEFLOW_HOME=/home/user/.cache/templateflow
+        TEMPLATEFLOW_USE_DATALAD=0
+        TEMPLATEFLOW_AUTOUPDATE=1
+        TEMPLATEFLOW_GET_TIMEOUT=10
+
+Changing a value updates the cached client configuration immediately. For example,
+enabling the DataLad backend is equivalent to instantiating a client with
+``TemplateFlowClient(use_datalad=True)`` because the command mutates the
+``CacheConfig`` object used by the global client::
+
+        $ templateflow config set TEMPLATEFLOW_USE_DATALAD 1
+        Updated TEMPLATEFLOW_USE_DATALAD → 1 (DataLad downloads will be used on next access)
+
+When the CLI is invoked afterwards, the cache will be re-initialized using
+``use_datalad=True`` without requiring any additional Python code.  The same
+mechanism applies to paths (``TEMPLATEFLOW_HOME``), origins, and timeout
+settings provided via ``templateflow config``.
+
+Updating an existing cache
+--------------------------
+The :mod:`templateflow.conf` module exposes an ``update`` helper that the CLI
+mirrors through ``templateflow update``.  Executing the command instructs the
+underlying :class:`templateflow.conf.cache.TemplateFlowCache` instance to refresh
+its content using the currently selected backend::
+
+        $ templateflow update --silent
+        Cache mode: S3
+        Cache root: /home/user/.cache/templateflow
+        TemplateFlow cache is up to date
+
+If ``TEMPLATEFLOW_USE_DATALAD`` (or ``--use-datalad``) is enabled, the command
+delegates to :class:`templateflow.conf.cache.DataladManager` and performs a
+recursive ``datalad update``.  Otherwise the S3 manager fetches new or changed
+files while keeping existing downloads intact.
+
+Wiping the cache
+----------------
+The ``templateflow wipe`` command is a thin wrapper around
+:meth:`templateflow.conf.cache.TemplateFlowCache.wipe`.  It clears the local cache
+and invalidates the in-memory layout so that subsequent ``templateflow`` CLI
+calls or new :class:`templateflow.client.TemplateFlowClient` instances trigger a clean re-install::
+
+        $ templateflow wipe
+        Removing cache at /home/user/.cache/templateflow …
+        Cache cleared; next access will reinstall the archive
+
+In DataLad mode the wipe operation reports that no deletion occurs because
+``TemplateFlowCache`` delegates to :class:`~templateflow.conf.cache.DataladManager`,
+preserving the working tree.  This makes it safe to toggle between backends via
+``templateflow config`` without unintentionally removing a managed repository.

docs/datalad.rst

@@ -5,6 +5,22 @@ Therefore, it is possible (and recommended for those who want to
 leverage the power of DataLad) to access the Archive using just
 DataLad.
 
+.. tip:: Prefer the Python client for routine access
+
+   The high-level :class:`templateflow.client.TemplateFlowClient` can be
+   configured with ``use_datalad=True`` (or via ``templateflow config set
+   TEMPLATEFLOW_USE_DATALAD 1``) to transparently manage the cache with
+   DataLad.  This is a good default when you want TemplateFlow to perform
+   ``datalad get`` and ``datalad update`` commands automatically while still
+   interacting with the archive through the familiar client API.
+
+.. note:: Drop down to raw DataLad when you need full control
+
+   Advanced workflows—such as pinning remotes, creating custom siblings, or
+   operating entirely offline—are better served by running DataLad commands
+   directly.  In those scenarios leave ``use_datalad`` disabled in the client
+   and use the instructions below to operate on the repository yourself.
+
 Installing the Archive
 ----------------------
 The archive is indexed by a superdataset, which can be installed with::