Implement Automatic CLI Documentation with MkDocs

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]'

docs/commands/multi.md

@@ -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/single.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/getting-started.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/index.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/troubleshooting.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`
+
+***

mkdocs.yml

@@ -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

pyproject.toml

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

scripts/generate_docs.py

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

site/404.html

@@ -0,0 +1,116 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+    <meta charset="utf-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+      <link rel="shortcut icon" href="/img/favicon.ico" />
+    <title>SSDraw</title>
+    <link rel="stylesheet" href="/css/theme.css" />
+    <link rel="stylesheet" href="/css/theme_extra.css" />
+        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" />
+
+    <!--[if lt IE 9]>
+      <script src="/js/html5shiv.min.js"></script>
+    <![endif]-->
+      <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
+      <script>hljs.highlightAll();</script> 
+</head>
+
+<body class="wy-body-for-nav" role="document">
+
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
+    <div class="wy-side-scroll">
+      <div class="wy-side-nav-search">
+          <a href="/." class="icon icon-home"> SSDraw
+        </a><div role="search">
+  <form id ="rtd-search-form" class="wy-form" action="//search.html" method="get">
+      <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" title="Type search term here" />
+  </form>
+</div>
+      </div>
+
+      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <ul>
+                <li class="toctree-l1"><a class="reference internal" href="/.">Home</a>
+                </li>
+              </ul>
+              <ul>
+                <li class="toctree-l1"><a class="reference internal" href="/getting-started/">Getting Started</a>
+                </li>
+              </ul>
+              <p class="caption"><span class="caption-text">Modules</span></p>
+              <ul>
+                  <li class="toctree-l1"><a class="reference internal" href="/commands/single/">single</a>
+                  </li>
+                  <li class="toctree-l1"><a class="reference internal" href="/commands/multi/">multi</a>
+                  </li>
+              </ul>
+      </div>
+    </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
+      <nav class="wy-nav-top" role="navigation" aria-label="Mobile navigation menu">
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="/.">SSDraw</a>
+
+      </nav>
+      <div class="wy-nav-content">
+        <div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation">
+  <ul class="wy-breadcrumbs">
+    <li><a href="/." class="icon icon-home" aria-label="Docs"></a></li>
+    <li class="wy-breadcrumbs-aside">
+    </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+            <div class="section" itemprop="articleBody">
+
+
+  <h1 id="404-page-not-found">404</h1>
+
+  <p><strong>Page not found</strong></p>
+
+
+            </div>
+          </div><footer>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <!-- Copyright etc -->
+  </div>
+
+  Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
+</footer>
+
+        </div>
+      </div>
+
+    </section>
+
+  </div>
+
+  <div class="rst-versions" role="note" aria-label="Versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+
+
+
+  </span>
+</div>
+    <script src="/js/jquery-3.6.0.min.js"></script>
+    <script>var base_url = "/";</script>
+    <script src="/js/theme_extra.js"></script>
+    <script src="/js/theme.js"></script>
+      <script src="/search/main.js"></script>
+    <script>
+        jQuery(function () {
+            SphinxRtdTheme.Navigation.enable(true);
+        });
+    </script>
+
+</body>
+</html>