add more docs

Author: jhrmnn

caf/cli/cli.py

@@ -29,7 +29,7 @@
 logging.getLogger('caf').setLevel(int(os.environ.get('CAF_DEBUG', logging.INFO)))
 
 
-@click.group(chain=True)
+@click.group()
 @click.pass_context
 def cli(ctx: click.Context) -> None:
     ctx.ensure_object(App)
@@ -38,6 +38,7 @@ def cli(ctx: click.Context) -> None:
 @cli.command()
 @click.pass_obj
 def init(app: App) -> None:
+    """Initialize a Git repository."""
     app.ensure_cafdir()
 
 
@@ -87,6 +88,7 @@ def run(
     maxerror: int,
     rulename: str,
 ) -> None:
+    """Run a given rule."""
     rule = import_fullname(rulename)
     task_filter = TaskFilter(pattern, no_path=not path)
     exception_buffer = ExceptionBuffer(maxerror)
@@ -104,6 +106,7 @@ def run(
 @click.argument('rulename', metavar='RULE', envvar='CAF_RULE')
 @click.pass_obj
 def status(app: App, rulename: str, pattern: List[str]) -> None:
+    """Print status of tasks."""
     rule = import_fullname(rulename)
     sess = app.session(warn=False, readonly=True, full_restore=True)
     ncols = len(STATE_COLORS) + 1
@@ -144,6 +147,7 @@ def status(app: App, rulename: str, pattern: List[str]) -> None:
 @click.argument('rulename', metavar='RULE', envvar='CAF_RULE')
 @click.pass_obj
 def graph(app: App, rulename: str) -> None:
+    """Open a pdf with the task graph."""
     rule = import_fullname(rulename)
     sess = app.session(warn=False, readonly=True, full_restore=True)
     with sess:
@@ -169,6 +173,7 @@ def checkout(
     done: bool,
     copy: bool,
 ) -> None:
+    """Checkout path-labeled tasks into a directory tree."""
     if blddir.exists() and force:
         shutil.rmtree(blddir)
     blddir.mkdir()

caf/rules/__init__.py

@@ -1,2 +1,2 @@
 from .rules import Rule, HookedRule, with_hook, labelled
-from .dirtask import dir_task
+from .dirtask import dir_task, DirtaskTmpdir

caf/rules/dirtask.py

@@ -37,9 +37,12 @@
 
 
 class HashingPath(ABC):
+    """Represents a path that guarantees immutability."""
+
     @property
     @abstractmethod
     def path(self) -> Path:
+        """the actual path"""
         ...
 
 
@@ -104,6 +107,12 @@ def checkout_files(
 
 
 class DirtaskTmpdir:
+    """
+    Context manager of a temporary directory that collects created files.
+
+    :param output_filter: true for files to be collected
+    """
+
     def __init__(self, output_filter: Callable[[str], bool] = None) -> None:
         sess = Session.active()
         fmngr = sess.storage.get('dir_task:file_manager')
@@ -143,6 +152,10 @@ def __exit__(self, exc_type: Any, *args: Any) -> None:
             self._ctx.__exit__(exc_type, *args)
 
     def result(self) -> DirTaskResult:
+        """
+        The collection of files created in the temporary directory. This is
+        available only after leaving the context.
+        """
         return self._outputs
 
 
@@ -151,6 +164,10 @@ def result(self) -> DirTaskResult:
 async def dir_task(
     exe: Union[HashingPath, bytes], inputs: Dict[str, Union[HashingPath, bytes, Path]]
 ) -> DirTaskResult:
+    """
+    Task rule with an executable and a collection of files as inputs and a
+    collection of output files as output.
+    """
     dirtask_tmpdir = DirtaskTmpdir(lambda p: p != EXE_NAME and p not in inputs)
     with dirtask_tmpdir as tmpdir:
         checkout_files(tmpdir, exe, inputs)

caf/rules/rules.py

@@ -2,6 +2,7 @@
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 import inspect
+from functools import wraps
 from typing import Any, Callable, TypeVar, Generic, Tuple, Optional, cast
 
 from ..tasks import Task, Corofunc
@@ -25,6 +26,7 @@ def __init__(self, corofunc: Corofunc[_T]) -> None:
             raise CafError(f'Task function is not a coroutine: {corofunc}')
         self._corofunc = corofunc
         self._label: Optional[str] = None
+        wraps(corofunc)(self)
 
     def __call__(self, *args: Any, **kwargs: Any) -> Task[_T]:
         kwargs.setdefault('label', self._label)

caf/sci/aims/aims.py

@@ -25,12 +25,20 @@ def _func_hash(self) -> str:
 
 
 class Aims(Pluggable):
+    """Instances of this class are task factories that create directory tasks
+    that represent calculations with FHI-aims.
+    """
+
     def __init__(self) -> None:
         Pluggable.__init__(self)
         for factory in default_plugins:
             factory()(self)
 
     def __call__(self, *, label: str = None, **kwargs: Any) -> Task[DirTaskResult]:
+        """Create an FHI-aims.
+
+        :param kwargs: processed by individual plugins
+        """
         self.run_plugins('process', kwargs, start=None)
         script = kwargs.pop('script').encode()
         inputs = {name: cont.encode() for name, cont in kwargs.pop('inputs')}
@@ -73,6 +81,9 @@ def process(self, kwargs: Dict[str, Any]) -> None:
 
 
 class SpeciesDefaults(AimsPlugin):
+    """Aims plugin that handles adding species defaults to control.in.
+    """
+
     def __init__(self, mod: Callable[..., Any] = None) -> None:
         self._species_defs: Dict[Tuple[Path, str], Dict[str, Any]] = {}
         self._mod = mod

caf/sci/aims/parse.py

@@ -12,6 +12,9 @@
 
 @Rule
 async def parse_aims(outputs: Dict[str, bytes]) -> Any:
+    """Task rule with an output of :class:`caf.sci.aims.Aims` as input and a
+    dictionary of parsed results as output.
+    """
     stdout = outputs['results.xml'].decode()
     parsed = parse_xml(io.StringIO(stdout))
     energies = {x['name']: x['value'][0] for x in parsed['energy']}