From 139841378de68cf247b3b0ba57c72cb70bafaccc Mon Sep 17 00:00:00 2001
From: Kelly Sovacool <kelly.sovacool@nih.gov>
Date: Mon, 26 Aug 2024 17:47:55 -0400
Subject: [PATCH] docs: add module docstrings

---
 src/ccbr_tools/gb2gtf.py    |  6 ++++++
 src/ccbr_tools/intersect.py | 16 ++++++++--------
 src/ccbr_tools/jobby.py     | 11 ++++++-----
 src/ccbr_tools/jobinfo.py   |  6 ++++--
 src/ccbr_tools/peek.py      |  8 ++++++--
 src/ccbr_tools/pkg_util.py  |  4 ++++
 src/ccbr_tools/shell.py     |  9 +++++++++
 7 files changed, 43 insertions(+), 17 deletions(-)

diff --git a/src/ccbr_tools/gb2gtf.py b/src/ccbr_tools/gb2gtf.py
index dec0c88..a4607ea 100644
--- a/src/ccbr_tools/gb2gtf.py
+++ b/src/ccbr_tools/gb2gtf.py
@@ -1,3 +1,9 @@
+"""
+Module for converting GenBank files to GTF format.
+
+Usage:
+    python gb2gtf.py sequence.gb > sequence.gtf
+"""
 # download GenBank file from NCBI and then
 # Usage:python gb2gtf.py sequence.gb  > sequence.gtf
 
diff --git a/src/ccbr_tools/intersect.py b/src/ccbr_tools/intersect.py
index 44e2c50..d1ff76a 100644
--- a/src/ccbr_tools/intersect.py
+++ b/src/ccbr_tools/intersect.py
@@ -1,11 +1,11 @@
-#!/usr/local/bin/python
-###################################################################
-# Skyler Kuhn
-# intersect
-# Find the intersect of the two files
-# Returns the inner join
-# USAGE: intersect file1 file2
-###################################################################
+"""
+Find the intersect of two files, returns the inner join
+
+Original author: Skyler Kuhn (@skchronicles)
+
+Usage:
+    intersect file1 file2
+"""
 from __future__ import print_function
 import sys
 
diff --git a/src/ccbr_tools/jobby.py b/src/ccbr_tools/jobby.py
index aeb8bcf..672d25f 100755
--- a/src/ccbr_tools/jobby.py
+++ b/src/ccbr_tools/jobby.py
@@ -1,9 +1,6 @@
-#!/usr/bin/env python3
-# Thanks @skchronicles
-# source: https://raw.githubusercontent.com/OpenOmics/mr-seek/2ecbbb2628b7102bf2cc23bc946858de2e09929f/workflow/scripts/jobby
-# -*- coding: UTF-8 -*-
-
 """
+Display job information for past slurm job IDs
+
 ABOUT:
     `jobby` will take your past jobs and display their job information.
     Why? We have pipelines running on several different clusters and
@@ -13,6 +10,10 @@
     getting job information to return to the user in a standardized
     format and unified cli.
 
+    Many thanks to the original author: Skyler Kuhn (@skchronicles)
+
+    Original source: https://raw.githubusercontent.com/OpenOmics/mr-seek/2ecbbb2628b7102bf2cc23bc946858de2e09929f/workflow/scripts/jobby
+
 REQUIRES:
   - python>=3.5
 
diff --git a/src/ccbr_tools/jobinfo.py b/src/ccbr_tools/jobinfo.py
index ee7d334..3539e40 100755
--- a/src/ccbr_tools/jobinfo.py
+++ b/src/ccbr_tools/jobinfo.py
@@ -1,6 +1,6 @@
-#!/usr/bin/env python3
-
 """
+Get HPC usage metadata for a list of slurm jobids on biowulf
+
 About:
     This wrapper script works only on BIOWULF!
     This script usage the "dashboard_cli" utility on biowulf to get HPC usage metadata
@@ -8,8 +8,10 @@
     line or extracted from a snakemake.log file. Using snakemake.log file option together
     with --failonly option lists path to the STDERR files for failed jobs. This can be
     very useful to debug failed Snakemake workflows.
+
 USAGE:
     $ jobinfo -h
+
 Example:
     $ jobinfo -j 123456,7891011
     $ jobinfo -s /path/to/snakemake.log
diff --git a/src/ccbr_tools/peek.py b/src/ccbr_tools/peek.py
index 62b5df1..42a4c79 100755
--- a/src/ccbr_tools/peek.py
+++ b/src/ccbr_tools/peek.py
@@ -1,5 +1,9 @@
-#!/usr/local/bin/python
-# -*- coding: utf-8 -*-
+"""
+Take a peek at tab-delimited files
+
+Usage:
+    peek <file.tsv> [buffer]
+"""
 from __future__ import print_function
 from pathlib import Path
 import sys
diff --git a/src/ccbr_tools/pkg_util.py b/src/ccbr_tools/pkg_util.py
index 276117f..5b1c305 100644
--- a/src/ccbr_tools/pkg_util.py
+++ b/src/ccbr_tools/pkg_util.py
@@ -175,15 +175,19 @@ def read_template(template_name):
 def use_template(template_name, output_filepath=None, **kwargs):
     """
     Uses a template, formats variables, and writes it to a file.
+
     Args:
         template_name (str): The name of the template to use.
         output_filepath (str, optional): The filepath to save the output file. If not provided, it will be written to `template_name` in the current working directory.
         **kwargs: Keyword arguments to fill in the template variables.
+
     Returns:
         None
+
     Raises:
         FileNotFoundError: If the template file is not found.
         IOError: If there is an error writing the output file.
+
     Examples:
         use_template("slurm_nxf_biowulf.sh", output_filepath="submit_slurm.sh", PIPELINE="CCBR_nxf", RUN_COMMAND="nextflow run main.nf -stub")
     """
diff --git a/src/ccbr_tools/shell.py b/src/ccbr_tools/shell.py
index e758ed5..a759337 100644
--- a/src/ccbr_tools/shell.py
+++ b/src/ccbr_tools/shell.py
@@ -1,3 +1,12 @@
+"""
+Utility functions for shell command execution.
+
+Example:
+    >>> shell_run("echo Hello, World!")
+    'Hello, World!\n'
+    >>> shell_run("invalid_command")
+    '/bin/sh: invalid_command: command not found\n'
+"""
 import contextlib
 import io
 import subprocess