doc: add docs

fgpyo/sam/__init__.py

@@ -237,6 +237,12 @@ def _pysam_open(
 ) -> SamFile:
     """Opens a SAM/BAM/CRAM for reading or writing.
 
+    This function permits reading from `stdin` and writing to `stdout`. The specified path may be
+    the UNIX conventional `"-"`, the more explicit `"stdin"` or `"stdout"`, or an absolute path to
+    either of the standard streams `"/dev/stdin"` or `"/dev/stdout"`.
+
+    When writing to `stdout`, the file type must be specified.
+
     Args:
         path: a file handle or path to the SAM/BAM/CRAM to read or write.
         open_for_reading: True to open for reading, false otherwise.
@@ -287,6 +293,8 @@ def reader(
 ) -> SamFile:
     """Opens a SAM/BAM/CRAM for reading.
 
+    To read from `stdin`, provide any of `"-"`, `"stdin"`, or `"/dev/stdin"` as the input `path`.
+
     Args:
         path: a file handle or path to the SAM/BAM/CRAM to read or write.
         file_type: the file type to assume when opening the file.  If None, then the file
@@ -303,15 +311,19 @@ def writer(
 ) -> SamFile:
     """Opens a SAM/BAM/CRAM for writing.
 
+    To write to `stdout`, provide any of `"-"`, `"stdout"`, or `"/dev/stdout"` as the output `path`.
+    **Note**: When writing to `stdout`, the `file_type` _must_ be given.
+
     Args:
         path: a file handle or path to the SAM/BAM/CRAM to read or write.
         header: Either a string to use for the header or a multi-level dictionary.  The
             multi-level dictionary should be given as follows.  The first level are the four
             types (‘HD’, ‘SQ’, ...). The second level are a list of lines, with each line being
             a list of tag-value pairs. The header is constructed first from all the defined
             fields, followed by user tags in alphabetical order.
-        file_type: the file type to assume when opening the file.  If None, then the
-            filetype will be auto-detected and must be a path-like object.
+        file_type: the file type to assume when opening the file.  If `None`, then the
+            filetype will be auto-detected and must be a path-like object. This argument is required
+            when writing to `stdout`.
     """
     # Set the header for pysam's AlignmentFile
     key = "text" if isinstance(header, str) else "header"