Updated git_ops and lazy doc strings.

Author: coordt

docsrc/api.rst

@@ -12,6 +12,7 @@ API Reference
    ~configuration
    ~data_merge
    ~git_ops
+   ~lazy
    ~pipeline
    ~templating
    ~utilities

docsrc/conf.py

@@ -61,6 +61,7 @@
 ]
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
+    "gitpython": ("https://gitpython.readthedocs.io/en/stable/", None),
 }
 
 templates_path = ["_templates"]

generate_changelog/git_ops.py

@@ -1,6 +1,6 @@
 """git information access."""
 
-from typing import Optional
+from typing import List, Optional
 
 import datetime
 import os
@@ -85,8 +85,16 @@ def parse_commits(repository: Repo, starting_rev: Optional[str] = None, ending_r
     return [repository.commit(commit) for commit in commits if commit]
 
 
-def get_tags(repository: Repo) -> list:
-    """Get all the tags in a repository."""
+def get_tags(repository: Repo) -> List[TagInfo]:
+    """
+    Get all the tags in a repository.
+
+    Args:
+        repository: The repository object containing the tags
+
+    Returns:
+        A list of TagInfo objects with the most recent first
+    """
     tags = repository.tags
     tags_list = []
 
@@ -114,8 +122,18 @@ def get_tags(repository: Repo) -> list:
     return tags_list
 
 
-def get_commits_by_tags(repository: Repo, tag_filter_pattern: str, starting_tag: Optional[str] = None) -> list:
-    """Group commits by the tags they belong to."""
+def get_commits_by_tags(repository: Repo, tag_filter_pattern: str, starting_tag: Optional[str] = None) -> List[dict]:
+    """
+    Group commits by the tags they belong to.
+
+    Args:
+        repository: The git repository object
+        tag_filter_pattern: A regular expression pattern that matches valid tags as versions
+        starting_tag: Only include tags after this one
+
+    Returns:
+        A list of dictionaries with tag information with most recent first
+    """
     from generate_changelog.utilities import pairs
 
     tags = [tag for tag in get_tags(repository) if re.match(tag_filter_pattern, tag.name)]

generate_changelog/lazy.py

@@ -14,16 +14,13 @@ class LazyObject:
     A wrapper for another class that can be used to delay instantiation of the wrapped object.
 
     Example:
-        ::
-            context = LazyObject(lambda: Context())
-
+            >>> context = LazyObject(lambda: Context())
             # Do some other stuff. Context is not evaluated yet.
-            some_other_code()
-
+            >>> some_other_code()
             # Only now is Context instantiated and evaluated,
             # since we attempt to access an attribute on it
             # using __getattr__ which in turn calls _setup().
-            print(context.run_id)
+            >>> print(context.run_id)
     """
 
     _wrapped = None