Merge pull request datalad#417 from mih/doc

Make dev-docs more accessible and organization more clear

datalad_next/archive_operations/__init__.py

@@ -1,4 +1,15 @@
-"""Archive operation handlers"""
+"""Handler for operations on various archive types
+
+All handlers implements the API defined by :class:`ArchiveOperations`.
+
+Available handlers:
+
+.. currentmodule:: datalad_next.archive_operations
+.. autosummary::
+   :toctree: generated
+
+   tarfile
+"""
 
 # allow for |-type UnionType declarations
 from __future__ import annotations
@@ -25,7 +36,23 @@
 
 
 class ArchiveOperations(ABC):
-    """
+    """Base class of all archives handlers
+
+    Any handler can be used as a context manager to adequately acquire and
+    release any resources necessary to access an archive. Alternatively,
+    the :func:`~ArchiveOperations.close()` method can be called, when archive
+    access is no longer needed.
+
+    In addition to the :func:`~ArchiveOperations.open()` method for accessing
+    archive item content, each handler implements the standard
+    ``__contains__()``, and ``__iter__()``.
+
+    ``__contains__()`` reports whether the archive contains an items of a given
+    identifier.
+
+    ``__iter__()`` provides an iterator that yields
+    :class:`~datalad_next.iter_collections.utils.FileSystemItem` instances with
+    information on each archive item.
     """
     def __init__(self, location: Any, *, cfg: ConfigManager | None = None):
         """
@@ -46,27 +73,39 @@ def __str__(self) -> str:
 
     @property
     def cfg(self) -> ConfigManager:
+        """ConfigManager given to the constructor, or the session default"""
         if self._cfg is None:
             self._cfg = datalad.cfg
         return self._cfg
 
     def __enter__(self):
+        """Default implementation that does nothing in particular"""
         return self
 
     def __exit__(self, exc_type, exc_value, traceback):
+        """Default implementation that only calls ``.close()``"""
         self.close()
-        # we have no desired to suppress exception, indicate standard
+        # we have no desire to suppress exception, indicate standard
         # handling by not returning True
         return
 
     @contextmanager
     @abstractmethod
     def open(self, item: Any) -> IO:
-        """
+        """Get a file-like for an archive item
+
+        Parameters
+        ----------
+        item:
+          Any identifier for an archive item supported by a particular handler
         """
         raise NotImplementedError
 
     def close(self) -> None:
+        """Default implementation for closing a archive handler
+
+        This default implementation does nothing.
+        """
         pass
 
     @abstractmethod

datalad_next/commands/__init__.py

@@ -1,4 +1,13 @@
-"""Components for basic functions of commands and their results"""
+"""Essential tooling for implementing DataLad commands
+
+This module provides the advanced command base class
+:class:`ValidatedInterface`, for implementing commands with uniform argument
+validation and structured error reporting.
+
+Beyond that, any further components necessary to implement command are imported
+in this module to offer a one-stop-shop experience. This includes
+``build_doc``, ``datasetmethod``, and ``eval_results``, among others.
+"""
 from __future__ import annotations
 
 from typing import Dict

datalad_next/config/__init__.py

@@ -1 +1,6 @@
+"""Configuration query and manipulation
+
+This modules imports the central ``ConfigManager`` class from DataLad core.
+"""
+
 from datalad.config import ConfigManager

datalad_next/credman/__init__.py

@@ -1 +1,9 @@
+"""Credential management
+
+.. currentmodule:: datalad_next.credman
+.. autosummary::
+   :toctree: generated
+
+   manager
+"""
 from .manager import CredentialManager

datalad_next/exceptions/__init__.py

@@ -1,5 +1,7 @@
 """All custom exceptions used in datalad-next"""
 
+# TODO rethink the purpose of this module and possibly
+# make it about *external* custom exceptions
 from datalad_next.runners import CommandError
 from datalad.support.exceptions import (
     CapturedException,

datalad_next/runners/__init__.py

@@ -1,3 +1,8 @@
+"""Execution of subprocesses
+
+This module import all relevant components for subprocess execution.
+"""
+
 # runners
 from datalad.runner import (
     GitRunner,

datalad_next/tests/fixtures.py

@@ -1,3 +1,5 @@
+"""Collection of fixtures for facilitation test implementations
+"""
 import logging
 import os
 from pathlib import Path

datalad_next/types/__init__.py

@@ -0,0 +1,10 @@
+"""Custom types and dataclasses
+
+.. currentmodule:: datalad_next.types
+.. autosummary::
+   :toctree: generated
+
+   annexkey
+   archivist
+   enums
+"""

datalad_next/uis/__init__.py

@@ -1,3 +1,8 @@
+"""UI abstractions for user communication
+
+This module imports all necessary components.
+"""
+
 # make more obvious that this is a frontend that behaves
 # differently depending on many conditions
 from datalad.ui import ui as ui_switcher

datalad_next/url_operations/__init__.py

@@ -1,5 +1,16 @@
-"""Abstract base class for URL operation handlers"""
+"""Handlers for operations on various URL types and protocols
 
+Available handlers:
+
+.. currentmodule:: datalad_next.url_operations
+.. autosummary::
+   :toctree: generated
+
+   any
+   file
+   http
+   ssh
+"""
 # allow for |-type UnionType declarations
 from __future__ import annotations
 

docs/source/index.rst

@@ -49,13 +49,16 @@ Command line reference
    cmd.rst
 
 
-Python utilities
-----------------
+Python tooling
+--------------
+
+``datalad-next`` comprises a number of more-or-less self-contained
+mini-packages providing particular functionality.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   pyutils.rst
+   Infrastructure classes and utilities <pyutils.rst>
 
 
 Git remote helpers

docs/source/pyutils.rst

@@ -1,29 +1,31 @@
 .. _pyutils:
 
-Python utilities
-****************
+Python tooling
+**************
+
+``datalad-next`` comprises a number of more-or-less self-contained
+mini-packages providing particular functionality. These implementations
+are candidates for a migration into the DataLad core package, and are
+provided here for immediate use. If and when components are migrated,
+transition modules will be kept to prevent API breakage in dependent
+packages.
+
 
 .. currentmodule:: datalad_next
 .. autosummary::
    :toctree: generated
 
-   commands.ValidatedInterface
-   config.ConfigManager
+   archive_operations
+   commands
+   config
    constraints
-   credman.manager
+   credman
    datasets
    exceptions
    iter_collections
+   runners
+   tests.fixtures
+   types
+   uis
    url_operations
-   url_operations.any
-   url_operations.file
-   url_operations.http
-   url_operations.ssh
    utils
-   utils.http_helpers
-   utils.multihash
-   utils.requests_auth
-   tests.fixtures
-   types.annexkey
-   types.archivist
-   types.enums