Merge pull request #9 from prameshsharma25/docs

Implement Automatic CLI Documentation with MkDocs

Author: prameshsharma25

Makefile

@@ -1,5 +1,5 @@
 format:
-	black --line-length 79 .
+	black .
 
 lint:
 	flake8 .
@@ -20,4 +20,13 @@ twine-upload:
 	twine upload dist/*
 
 remove-dist:
-	rm -rf dist/*
+	rm -rf dist/*
+
+generate-cli-docs:
+	python3 scripts/generate_docs.py
+
+serve-docs: generate-cli-docs
+	mkdocs serve
+
+install-docs:
+	pip install '.[docs]'

SSDraw.ipynb

@@ -0,0 +1,12 @@
+# SSDraw multi Command
+
+This section documents the `ssdraw multi` command.
+
+```bash
+usage: generate_docs.py multi [-h] -i INPUT -o OUTPUT
+
+options:
+  -h, --help           show this help message and exit
+  -i, --input INPUT    Name of input script
+  -o, --output OUTPUT  Name of output directory
+```

docs/commands/multi.md

@@ -0,0 +1,39 @@
+# SSDraw single Command
+
+This section documents the `ssdraw single` command.
+
+```bash
+usage: generate_docs.py single [-h] [-f FASTA] [-p PDB] [-n NAME] [-o OUTPUT] [--SS SS] [--chain_id CHAIN_ID] [--color_map [COLOR_MAP ...]]
+                               [--scoring_file SCORING_FILE] [--color COLOR] [-conservation_score] [--output_file_type OUTPUT_FILE_TYPE] [-bfactor]
+                               [-mview] [--dpi DPI] [--ticks TICKS] [--start START] [--end END] [--dssp_exe DSSP_EXE] [--consurf CONSURF]
+                               [--fontsize FONTSIZE] [--fontcolor FONTCOLOR]
+
+options:
+  -h, --help            show this help message and exit
+  -f, --fasta FASTA     (required) sequence/alignment file in fasta format
+  -p, --pdb PDB         (required) pdb file
+  -n, --name NAME       (required) id of the protein in the alignment file
+  -o, --output OUTPUT   (required) name for output file
+  --SS SS               secondary structure annotation in DSSP or .horiz format. If this option is not provided, SSDraw will compute secondary structure
+                        from the given PDB file with DSSP.
+  --chain_id CHAIN_ID   chain id to use in pdb. Defaults to chain A.
+  --color_map [COLOR_MAP ...]
+                        color map to use for heat map
+  --scoring_file SCORING_FILE
+                        custom scoring file for alignment
+  --color COLOR         color for the image. Can be a color name (eg. white, black, green), or a hex code
+  -conservation_score   score alignment by conservation score
+  --output_file_type OUTPUT_FILE_TYPE
+                        output file type. Options: png, ps, eps, tif, svg
+  -bfactor              score by B-factor
+  -mview                color by mview color map
+  --dpi DPI             dpi to use for final plot
+  --ticks TICKS         set ticks at every nth position
+  --start START
+  --end END
+  --dssp_exe DSSP_EXE   The path to your dssp executable. Default: mkdssp
+  --consurf CONSURF     consurf or rate4site file to color image with. If rate4site file is given, SSDraw will convert raw scores to grades.
+  --fontsize FONTSIZE   font size for residue numbers
+  --fontcolor FONTCOLOR
+                        font color for residue numbers
+```

docs/commands/single.md

@@ -0,0 +1,9 @@
+## Installation
+
+The easiest way to install SSDraw is via pip:
+
+```bash
+pip install SSDraw
+```
+
+You can find the package on PyPi [here](https://pypi.org/project/SSDraw/).

docs/getting-started.md

@@ -0,0 +1,4 @@
+# SSDraw
+SSDraw is a program that generates publication-quality protein secondary structure diagrams from three-dimensional protein structures. To depict relationships between secondary structure and other protein features, diagrams can be colored by conservation score, B-factor, or custom scoring.
+
+SSDraw also has a **colab notebook** available (only usable for Chrome). The notebook can be accessed [here](https://colab.research.google.com/github/ethanchen1301/SSDraw/blob/main/SSDraw.ipynb).

docs/index.md

@@ -0,0 +1,32 @@
+# Troubleshooting & Common Issues
+
+This section addresses frequently encountered problems and provides solutions.
+
+***
+
+## Issue: Amino Acid Sequence Overlap/Jumbling
+
+### Problem
+When the secondary structure diagram is **quite long** (i.e., for large proteins), the residue numbering and/or **amino acid sequence often overlaps or becomes jumbled** together, making it unreadable.
+
+### Solution
+You can adjust the size of the residue numbers and sequence labels by changing the default font size. Use the **`--fontsize`** flag followed by a numerical value. The default size is **12**, which may be too large for high-density diagrams. Try reducing it (e.g., `--fontsize 8`) until the text is clearly separated.
+
+* **Example:** `ssdraw single ... --fontsize 8`
+
+***
+
+## Issue: Saving Secondary Structure to a Specific File Format
+
+### Problem
+I need to save the generated secondary structure diagram in a **high-quality vector format** (like SVG or EPS) or a specific raster format (like TIFF) instead of the default PNG.
+
+### Solution
+You can specify the desired output file type using the **`--output_file_type`** flag. This is particularly useful for generating **publication-quality figures**.
+
+The supported output file types are: **`png`**, **`ps`**, **`eps`**, **`tif`**, and **`svg`**.
+
+* **To save as a vector graphic:** `ssdraw single ... --output_file_type svg`
+* **To save as a high-resolution image:** `ssdraw single ... --output_file_type tif`
+
+***

docs/troubleshooting.md

@@ -0,0 +1,11 @@
+site_name: SSDraw
+
+nav:
+    - Home: 'index.md'
+    - Getting Started: 'getting-started.md'
+    - Modules:
+        - single: 'commands/single.md'
+        - multi: 'commands/multi.md'
+    - Troubleshooting: 'troubleshooting.md'
+
+theme: readthedocs

mkdocs.yml

@@ -23,8 +23,8 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-tests = [
-    "pytest"
+docs = [
+    "mkdocs",
 ]
 
 [project.scripts]

pyproject.toml

@@ -0,0 +1,29 @@
+import io
+
+from contextlib import redirect_stdout
+from SSDraw.cli import get_args
+
+
+def generate_help(command, filename):
+    f = io.StringIO()
+    with redirect_stdout(f):
+        try:
+            get_args(argv=[command, "--help"])
+        except SystemExit:
+            pass
+
+    help_output = f.getvalue()
+
+    with open(f"docs/commands/{filename}.md", "w") as doc_file:
+        doc_file.write(f"# SSDraw {command} Command\n\n")
+        doc_file.write(f"This section documents the `ssdraw {command}` command.\n\n")
+        doc_file.write("```bash\n")
+        doc_file.write(help_output)
+        doc_file.write("```\n")
+
+
+if __name__ == "__main__":
+    generate_help("single", "single")
+    generate_help("multi", "multi")
+
+    print("CLI documentation updated in docs/commands/")