Merge pull request #627 from mih/docs

Uplift Python API docs

datalad_next/config/__init__.py

@@ -1,6 +1,12 @@
 """Configuration query and manipulation
 
-This modules imports the central ``ConfigManager`` class from DataLad core.
+This modules provides the central ``ConfigManager`` class.
+
+.. currentmodule:: datalad_next.config
+.. autosummary::
+   :toctree: generated
+
+   ConfigManager
 """
 
 from datalad.config import ConfigManager

datalad_next/consts/__init__.py

@@ -1,4 +1,19 @@
 """Common constants
+
+COPY_BUFSIZE
+  ``shutil`` buffer size default, with Windows platform default changes
+  backported from Python 3.10.
+
+PRE_INIT_COMMIT_SHA
+  SHA value for ``git hash-object -t tree /dev/null``, i.e. for nothing.
+  This corresponds to the state of a Git repository before the first commit
+  is made.
+
+on_linux
+  ``True`` if executed on the Linux platform.
+
+on_windows
+  ``True`` if executed on the Windows platform.
 """
 
 # import from "utils", but these really are constants

datalad_next/datasets/__init__.py

@@ -15,70 +15,35 @@
 implements paradigms and behaviors that are no longer common to the rest of the
 DataLad API. :class:`LegacyGitRepo` and :class:`LegacyAnnexRepo` should no
 longer be used in new developments, and are not documented here.
-"""
 
-from pathlib import Path
+
+.. currentmodule:: datalad_next.datasets
+.. autosummary::
+   :toctree: generated
+
+   Dataset
+   LeanGitRepo
+   LeanAnnexRepo
+   LegacyGitRepo
+   LegacyAnnexRepo
+"""
 
 from datalad.distribution.dataset import (
     Dataset,
     # this does nothing but provide documentation
     # only kept here until this command is converted to
     # pre-call parameter validation
+    # TODO REMOVE FOR V2.0
     EnsureDataset as NoOpEnsureDataset,
+    # TODO REMOVE FOR V2.0
     datasetmethod,
+    # TODO REMOVE FOR V2.0
     resolve_path,
 )
 from datalad.dataset.gitrepo import GitRepo as LeanGitRepo
+from datalad.support.gitrepo import GitRepo as LegacyGitRepo
 
 from datalad.support.gitrepo import GitRepo as LegacyGitRepo
 from datalad.support.annexrepo import AnnexRepo as LegacyAnnexRepo
 
-
-class LeanAnnexRepo(LegacyAnnexRepo):
-    """git-annex repository representation with a minimized API
-
-    This is a companion of :class:`LeanGitRepo`. In the same spirit, it
-    restricts its API to a limited set of method that extend
-    :class:`LeanGitRepo`.
-
-    """
-    #CA .. autosummary::
-
-    #CA    call_annex
-    #CA    call_annex_oneline
-    #CA    call_annex_success
-    # list of attributes permitted in the "lean" API. This list extends
-    # the API of LeanGitRepo
-    # TODO extend whitelist of attributes as necessary
-    _lean_attrs = [
-        #CA # these are the ones we intend to provide
-        #CA 'call_annex',
-        #CA 'call_annex_oneline',
-        #CA 'call_annex_success',
-        # and here are the ones that we need to permit in order to get them
-        # to run
-        '_check_git_version',
-        #CA '_check_git_annex_version',
-        # used by AnnexRepo.__init__() -- should be using `is_valid()`
-        'is_valid_git',
-        'is_valid_annex',
-        '_is_direct_mode_from_config',
-        #CA '_call_annex',
-        #CA 'call_annex_items_',
-    ]
-
-    # intentionally limiting to just `path` as the only constructor argument
-    def __new__(cls, path: Path):
-        for attr in dir(cls):
-            if not hasattr(LeanGitRepo, attr) \
-                    and callable(getattr(cls, attr)) \
-                    and attr not in LeanAnnexRepo._lean_attrs:
-                setattr(cls, attr, _unsupported_method)
-
-        obj = super(LegacyAnnexRepo, cls).__new__(cls)
-
-        return obj
-
-
-def _unsupported_method(self, *args, **kwargs):
-    raise NotImplementedError('method unsupported by LeanAnnexRepo')
+from .annexrepo import LeanAnnexRepo

datalad_next/datasets/annexrepo.py

@@ -0,0 +1,54 @@
+from pathlib import Path
+
+from datalad.dataset.gitrepo import GitRepo as LeanGitRepo
+from datalad.support.annexrepo import AnnexRepo as LegacyAnnexRepo
+
+
+class LeanAnnexRepo(LegacyAnnexRepo):
+    """git-annex repository representation with a minimized API
+
+    This is a companion of :class:`LeanGitRepo`. In the same spirit, it
+    restricts its API to a limited set of method that extend
+    :class:`LeanGitRepo`.
+
+    """
+    #CA .. autosummary::
+
+    #CA    call_annex
+    #CA    call_annex_oneline
+    #CA    call_annex_success
+    # list of attributes permitted in the "lean" API. This list extends
+    # the API of LeanGitRepo
+    # TODO extend whitelist of attributes as necessary
+    _lean_attrs = [
+        #CA # these are the ones we intend to provide
+        #CA 'call_annex',
+        #CA 'call_annex_oneline',
+        #CA 'call_annex_success',
+        # and here are the ones that we need to permit in order to get them
+        # to run
+        '_check_git_version',
+        #CA '_check_git_annex_version',
+        # used by AnnexRepo.__init__() -- should be using `is_valid()`
+        'is_valid_git',
+        'is_valid_annex',
+        '_is_direct_mode_from_config',
+        #CA '_call_annex',
+        #CA 'call_annex_items_',
+    ]
+
+    # intentionally limiting to just `path` as the only constructor argument
+    def __new__(cls, path: Path):
+        for attr in dir(cls):
+            if not hasattr(LeanGitRepo, attr) \
+                    and callable(getattr(cls, attr)) \
+                    and attr not in LeanAnnexRepo._lean_attrs:
+                setattr(cls, attr, _unsupported_method)
+
+        obj = super(LegacyAnnexRepo, cls).__new__(cls)
+
+        return obj
+
+
+def _unsupported_method(self, *args, **kwargs):
+    raise NotImplementedError('method unsupported by LeanAnnexRepo')

datalad_next/exceptions/__init__.py

@@ -1,4 +1,14 @@
-"""All custom exceptions used in datalad-next"""
+"""Special purpose exceptions
+
+.. currentmodule:: datalad_next.exceptions
+.. autosummary::
+   :toctree: generated
+
+   CapturedException
+   IncompleteResultsError
+   NoDatasetFound
+"""
+# we cannot have CommandError above, sphinx complains
 
 # TODO rethink the purpose of this module and possibly
 # make it about *external* custom exceptions
@@ -9,6 +19,7 @@
     NoDatasetFound,
 )
 
+# TODO REMOVE FOR V2.0 (they are specific to that module
 from datalad_next.url_operations import (
     UrlOperationsRemoteError,
     UrlOperationsAuthenticationError,

datalad_next/runners/__init__.py

@@ -55,12 +55,15 @@
 )
 
 # runners
+# TODO REMOVE FOR V2.0
 from datalad.runner import (
     GitRunner,
     Runner,
 )
+# TODO REMOVE FOR V2.0
 from datalad.runner.nonasyncrunner import ThreadedRunner
 # protocols
+# TODO REMOVE FOR V2.0
 from datalad.runner import (
     KillOutput,
     NoCapture,
@@ -69,7 +72,9 @@
     StdErrCapture,
     StdOutErrCapture,
 )
+# TODO REMOVE FOR V2.0
 from datalad.runner.protocol import GeneratorMixIn
+# TODO REMOVE FOR V2.0
 from .protocols import (
     NoCaptureGeneratorProtocol,
     StdOutCaptureGeneratorProtocol,
@@ -81,13 +86,16 @@
 from datalad_next.exceptions import CommandError
 
 # utilities
+# TODO REMOVE FOR V2.0
 from datalad.runner.nonasyncrunner import (
     STDOUT_FILENO,
     STDERR_FILENO,
 )
+# TODO REMOVE FOR V2.0
 from datalad.runner.utils import (
     LineSplitter,
 )
+# TODO REMOVE FOR V2.0
 from subprocess import (
     DEVNULL,
 )

datalad_next/uis/__init__.py

@@ -1,6 +1,11 @@
 """UI abstractions for user communication
 
-This module imports all necessary components.
+.. currentmodule:: datalad_next.uis
+.. autosummary::
+   :toctree: generated
+
+   ansi_colors
+   ui_switcher
 """
 
 # make more obvious that this is a frontend that behaves