docs: add module docstrings

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
 

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
 

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
 

src/ccbr_tools/jobinfo.py

@@ -1,15 +1,17 @@
-#!/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
     for a list of slurm jobids. These slurm jobids can be either provided at command
     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

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

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")
     """

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