update docstrings

examples/code/python_ast.py

@@ -1,3 +1,10 @@
+"""
+Define functions to create an abstract syntax tree (AST) graph model using the 'graphinate' library.
+The 'ast_graph_model' function parses the AST of a specified class and creates nodes and edges for the graph model.
+The nodes represent AST nodes with their type and label, while the edges represent relationships between AST nodes.
+"""
+
+
 import ast
 import hashlib
 import inspect
@@ -35,6 +42,13 @@ def _ast_edge(parsed_ast: AST):
 
 
 def ast_graph_model():
+    """
+    Create an abstract syntax tree (AST) graph model.
+
+    Returns:
+        GraphModel: A graph model representing the AST nodes and their relationships.
+    """
+
     graph_model = graphinate.model(name='AST Graph')
 
     root_ast_node = ast.parse(inspect.getsource(graphinate.builders.D3Builder))

examples/code/python_dependencies.py

@@ -6,6 +6,13 @@
 
 
 def dependency_graph_model():
+    """
+    Generate a dependency graph model.
+
+    Returns:
+        GraphModel: A graph model representing the dependency graph.
+    """
+
     options = get_options(args=None)
     handle_non_host_target(options)
 

examples/github/_client.py

@@ -27,6 +27,19 @@
 
 @functools.lru_cache
 def github_user(user_id: Optional[str] = None) -> Union[NamedUser, AuthenticatedUser]:
+    """
+    Get the GitHub user object for the specified user ID or the authenticated user.
+
+    Parameters:
+        user_id (Optional[str]): The ID of the user to retrieve.
+                                 If not provided, retrieve the authenticated user.
+
+    Returns:
+        Union[NamedUser, AuthenticatedUser]: The GitHub user object corresponding to the user ID provided,
+                                             or the authenticated user if no user ID is specified.
+    Note:
+        This function requires authentication with a valid GitHub token.
+    """
     user = client.get_user(user_id) if user_id else client.get_user()
     return user
 
@@ -35,6 +48,23 @@ def github_user(user_id: Optional[str] = None) -> Union[NamedUser, Authenticated
 def github_repositories(
         user_id: Optional[str] = None,
         repo_id: Optional[str] = None) -> Iterable[Repository]:
+    """
+    Get the GitHub repositories for the specified user ID or the authenticated user.
+
+    Parameters:
+        user_id (Optional[str]): The ID of the user whose repositories to retrieve.
+                                 If not provided, retrieve repositories of the authenticated user.
+        repo_id (Optional[str]): The ID of the repository to retrieve.
+                                 If provided, only that repository will be returned.
+
+    Returns:
+        Iterable[Repository]:
+        A list of GitHub repository objects corresponding to the user ID and/or repository ID provided.
+
+    Note:
+        This function requires authentication with a valid GitHub token.
+    """
+
     user = github_user(user_id)
     if repo_id and (repo := user.get_repo(name=repo_id)):
         return [repo]
@@ -45,6 +75,34 @@ def github_repositories(
 def github_commits(
         repo: Repository,
         commit_id: Optional[str] = None) -> Iterable[Commit]:
+    """
+    Retrieve commits from a GitHub repository.
+
+    Parameters:
+        repo (Repository): The GitHub repository object from which to retrieve commits.
+        commit_id (str, optional): The ID of the commit to retrieve.
+                                   If provided, only that commit will be returned.
+                                   Defaults to None.
+
+    Returns:
+        Iterable[Commit]: An Iterable of Commit objects representing the commits in the repository.
+
+    Example:
+        To retrieve all commits from a repository:
+        ```
+        for commit in github_commits(repo):
+            print(commit)
+        ```
+
+        To retrieve a specific commit by ID:
+        ```
+        for commit in github_commits(repo, commit_id='abcdef123456'):
+            print(commit)
+        ```
+
+    Note:
+        This function requires authentication with a valid GitHub token.
+    """
     if commit_id and (commit := repo.get_commit(sha=commit_id)):
         yield commit
     else:
@@ -54,6 +112,19 @@ def github_commits(
 def github_files(
         commit: Commit,
         file_id: Optional[str] = None) -> Iterable[File]:
+    """
+    Retrieves Files from a GitHub Commit
+
+    Parameters:
+        commit (Commit): A Commit object from the GitHub API.
+        file_id (Optional[str]): An optional parameter specifying the filename to filter the files. Default is None.
+
+    Returns:
+        Iterable[File]: An Iterable of File objects based on the filtering criteria.
+
+    Note:
+        This function requires authentication with a valid GitHub token.
+    """
     files: list[File] = commit.files
     if file_id:
         yield from [file for file in files if file.filename == file_id]

examples/github/followers.py

@@ -1,3 +1,9 @@
+"""
+Defines a function `followers_graph_model` that creates a graph model representing GitHub followers.
+It recursively fetches followers of a given user up to a specified maximum depth.
+The function yields edges between users in the graph.
+"""
+
 from typing import Optional
 
 import graphinate
@@ -7,6 +13,16 @@
 
 
 def followers_graph_model(max_depth: int = DEPTH):
+    """
+    Create a graph model representing GitHub followers.
+
+    Args:
+        max_depth (int): The maximum depth to fetch followers recursively (default is 0).
+
+    Returns:
+        GraphModel: A graph model representing GitHub followers.
+    """
+
     graph_model = graphinate.model(name='Github Followers Graph')
 
     def _followers(user_id: Optional[str] = None, depth: int = 0, **kwargs):

examples/github/repositories.py

@@ -8,6 +8,13 @@
 
 
 def repo_graph_model():  # noqa: C901
+    """
+    Create a graph model for GitHub repositories.
+
+    Returns:
+        GraphModel: A graph model representing GitHub repositories with nodes and edges.
+    """
+
     graph_model = graphinate.model(name='GitHub Repository Graph')
 
     @graph_model.edge

examples/math/graph_atlas.py

@@ -35,6 +35,21 @@ def spiral_torus_edges(n, k):
 
 
 def atlas():
+    """
+    Generate a dictionary of various graph structures and models based on the provided atlas.
+    The function creates different types of graphs and models using NetworkX library.
+    The generated graphs include Tetrahedron, Cube, Octahedron, Dodecahedron, Icosahedron, Tesseract, Truncated Cube,
+    Truncated Tetrahedron, Ladder, Ring, Möbius, Cylinder, Spiral, Spiral Torus, and Circulant[10,[2]].
+    Additionally, the function includes adjacency mappings for specific named graphs like
+    Buckyball - Truncated Icosahedral Graph, D30 - Rhombic Triacontahedral Graph, Small Rhombicosidodecahedral Graph,
+    Small Rhombicuboctahedral Graph, Great Rhombicosidodecahedral Graph, Disdyakis Dodecahedral Graph,
+    Deltoidal Icositetrahedral Graph, Icosidodecahedral Graph, Deltoidal Hexecontahedral Graph, Kocohl74,
+    Utility Graph, Errara Graph, and Dragon Curve Blob 6.
+    The adjacency mappings define the connections between nodes in each named graph.
+    The function returns a dictionary
+    containing the named graphs as keys and their corresponding NetworkX graph objects as values.
+    """
+
     ladder_size = 16
     ladder = nx.ladder_graph(ladder_size)
 
@@ -775,6 +790,21 @@ def edges_iter(adjacency_list: dict[int, [int]]):
 
 
 def models(iterable):
+    """
+    Generate a graph model based on the provided iterable of graphs.
+    The function creates a graph model named 'Graph Atlas' using the 'graphinate' library.
+    It then combines all the graphs from the input iterable into a single disjoint union graph using NetworkX library.
+    The function defines edges for the combined graph by iterating over all edges in the disjoint union graph and
+    yielding dictionaries with 'source' and 'target' keys representing the edge connections.
+    Finally, the function yields the created graph model containing the combined graph with defined edges.
+
+    Args:
+        iterable: An iterable containing graphs to be combined into a single graph model.
+
+    Yields:
+        GraphModel: A graph model containing the combined graph with defined edges.
+    """
+
     graph_model = graphinate.model('Graph Atlas')
 
     graph_atlas = nx.disjoint_union_all(g for _, g in iterable)

examples/math/polygonal_graph.py

@@ -5,7 +5,17 @@
 N: int = 8
 
 
-def get_graph_model(number_of_sides: int = N):
+def polygonal_graph_model(number_of_sides: int = N):
+    """
+    Create a polygonal graph model.
+
+    Args:
+        number_of_sides (int): Number of sides in the polygon. Defaults to N.
+
+    Returns:
+        GraphModel: A graph model representing a polygonal graph.
+    """
+
     # Define GraphModel
     graph_model = graphinate.model(name="Octagonal Graph")
 
@@ -19,7 +29,7 @@ def edge():
     return graph_model
 
 
-model = get_graph_model()
+model = polygonal_graph_model()
 
 if __name__ == '__main__':
     use_materialize = True

examples/system/processes.py

@@ -7,6 +7,13 @@
 
 
 def processes_graph_model():
+    """
+    Create a graph model representing processes and their parent-child relationships.
+
+    Returns:
+        GraphModel: A graph model representing processes and their parent-child relationships.
+    """
+
     graph_model = graphinate.model("Processes Graph")
 
     def processes() -> Iterable[psutil.Process]:

examples/web/page_links.py

@@ -9,6 +9,16 @@
 
 
 def page_links_graph_model(max_depth: int = DEFAULT_MAX_DEPTH):
+    """
+    Create a graph model based on page links.
+
+    Args:
+        max_depth (int, optional): The maximum depth to crawl for page links. Defaults to DEFAULT_MAX_DEPTH.
+
+    Returns:
+        GraphModel: A graph model representing the page links.
+    """
+
     def _links(url: str, depth=0, **kwargs):
         reqs = requests.get(url)
         logger.debug('Analyzing Page: {url}')

src/graphinate/color.py

@@ -10,10 +10,11 @@
 def node_color_mapping(graph: nx.Graph, cmap: Union[str, mpl.colors.Colormap] = "tab20") -> Mapping:
     """
     Parameters:
-        graph: graph_id
-        cmap : str or `~matplotlib.colors.Colormap` - The colormap used to map values to RGBA colors.
+        graph: nx.Graph - The input graph for which node colors need to be mapped.
+        cmap: Union[str, mpl.colors.Colormap], optional - The colormap used to map values to RGBA colors.
+              Default is "tab20".
     Returns:
-        Nodes RGBA Color list.
+        Mapping - A dictionary mapping nodes to their corresponding RGBA colors based on the colormap.
     """
     type_lookup = {t: i for i, t in enumerate(graph.graph['node_types'].keys())}
     color_lookup = {node: type_lookup.get(data.get('type'), 0) for node, data in graph.nodes.data()}