Initial setup of external docs

.github/workflows/documentation.yaml

@@ -0,0 +1,29 @@
+name: documentation
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - name: Install dependencies
+        run: |
+          pip install sphinx myst_parser furo sphinx-copybutton sphinx-argparse
+      - name: Sphinx build
+        run: |
+          sphinx-build -M html docs/source/ docs/build/
+      - name: Disable Jekyll
+        run: touch docs/build/html/.nojekyll
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build/html
+          force_orphan: true

.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: Run Tests
+
+on:
+    push:
+        branches: ["main"]
+    pull_request:
+        branches: ["main"]
+
+jobs:
+    test:
+        runs-on: ubuntu-latest
+
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up environment
+              uses: actions/setup-python@v5
+              with: 
+                  python-version: "3.10"
+
+            - name: Install uv
+              run: |
+                  curl -LsSf https://astral.sh/uv/install.sh | sh
+
+            - name: Install dependencies
+              run: |
+                  uv sync --group dev --extra cpu
+
+            - name: Run tests
+              run: |
+                  uv run pytest --device=cpu

README.md

@@ -6,29 +6,42 @@ HBDesigner is an algorithm that designs highly-connected hydrogen bonding networ
 
 ## Installation
 
-HBDesigner can be installed using `mamba` or `Pixi`. The following will create a `mamba` environment called `hbdesigner` with all necessary dependencies.
+HBDesigner can be installed using `mamba`, `uv`, or `Pixi`. 
 ```
+# first, clone the repo 
 git clone https://github.com/Kuhlman-Lab/HBDesigner.git
 cd HBDesigner/
+```
+To create a virtual environment with `mamba` for use on a GPU or CPU, respectively:
+```
+# for running on a GPU
 mamba env create -f env.yaml
 pip install .
+
+# for running on a CPU
+mamba env create -f env_cpu.yaml
+pip install .
+```
+To create a virtual environment with `uv` for use on a GPU or CPU respectively:
+```
+# for running on a GPU
+uv pip install -e ".[gpu]"
+
+# for running on a CPU
+uv pip install -e ".[cpu]"
 ```
 We also provide an alternative install method using `Pixi`. The following will create a `Pixi` project in the `HBDesigner` root directory:
 ```
 git clone https://github.com/Kuhlman-Lab/HBDesigner.git
 cd HBDesigner/
 pixi install
+
+# to install with pixi to run on a CPU instead use
+pixi install -e cpu
 ```
 
 The `Pixi` installation is much faster than `mamba`, but requires slightly more awkward syntax when running `HBDesigner`. See `examples/monomer/run_with_pixi` for an example.
 
-HBDesigner can be installed using the provided `install_hbdesigner.sh` script. This script requires the `mamba` package manager, but it can be readily adapted to use other package managers.
-```
-git clone https://github.com/Kuhlman-Lab/HBDesigner.git
-cd HBDesigner/
-sh install_hbdesigner.sh
-```
-
 ## Using HBDesigner
 
 A detailed guide for running HBDesigner on your protein(s) of interest can be found at `examples/README.md`, along with many example runscripts for common design scenarios.
@@ -46,4 +59,4 @@ The HBDesigner source code and model weights are provided under an MIT license (
 If you find HBDesigner useful for your own work, please use the following citation:
 ```
 TBD
-```
+```

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/cli_arguments.rst

@@ -0,0 +1,6 @@
+CLI Arguments
+=============
+
+.. argparse::
+    :module: hbdesigner.inference.parsers
+    :func: get_hbdes_parser

docs/source/conf.py

@@ -0,0 +1,63 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath("../../"))
+
+project = 'HBDesigner'
+copyright = '2026, Henry Dieckhaus, Kuhlman Lab'
+author = 'Henry Dieckhaus, Kuhlman Lab'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["myst_parser",
+              "sphinx_copybutton",
+              "sphinxarg.ext",
+              ]
+
+templates_path = ['_templates']
+exclude_patterns = ["readme.md", "readmelink.md", "readme_link.rst"]
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']
+
+html_theme_options = {
+    "sidebar_hide_name":False,
+    #"announcement": "<em>THIS DOCUMENTATION IS CURRENTLY UNDER CONSTRUCTION</em>",
+    "light_css_variables": {
+        "color-brand-primary": "#F68A33", # Rosetta Teal
+        "color-brand-content": "#37939B", # Rosetta Orange
+        #"color-admonition-background": "#CCE8E8", # Rosetta light orange
+        "font-stack": "Open Sans, sans-serif",
+        "font-stack--headings": "Open Sans, sans-serif",
+        "color-background-hover": "#DCE8E8ff",
+        "color-announcement-background" : "#F68A33dd",
+        "color-announcement-text": "#070707",
+        "color-brand-visited": "#37939B",
+        },
+    "dark_css_variables": {
+        "color-brand-primary": "#37939B", # Rosetta teal
+        "color-brand-content": "#F68A33", # Rosetta orange
+        #"color-admonition-background": "#20565B", # Rosetta light orange
+        "font-stack": "Open Sans, sans-serif",
+        "font-stack--headings": "Open Sans, sans-serif",
+        "color-brand-visited": "#37939B",
+        }
+    }
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+    }

docs/source/index.rst

@@ -0,0 +1,20 @@
+.. HBDesigner documentation master file, created by
+   sphinx-quickstart on Wed Apr  1 10:47:17 2026.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+HBDesigner Documentation
+========================
+
+Welcome to the official documentation for [HBDesigner](https://github.com/Kuhlman-Lab/HBDesigner). 
+
+HBDesigner is a machine learning tool that designs highly-connected hydrogen bonding networks based on user-defined constraints and an input protein backbone. 
+
+Make sure to read through the [HBDesigner README](https://github.com/Kuhlman-Lab/HBDesigner/blob/main/README.md) for an overview of the tool, its features, and how to get started.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   cli_arguments.rst
+   installation_guide.md

docs/source/installation_guide.md

@@ -0,0 +1,91 @@
+# Installation Guide
+
+## Contents
+
+
+---
+## Installation with Conda
+
+### GPU
+
+### CPU
+
+---
+## Installation with Mamba
+
+### GPU
+
+### CPU
+
+---
+## Installation with uv
+
+### GPU
+
+### CPU
+
+---
+## Installation with pixi
+
+### GPU
+### CPU
+
+(cuda_version)=
+## Adjusting for the CUDA version available on your system
+The various installation files (`env.yaml`, `pyproject.toml`) were created for systems running CUDA 12.8. 
+
+If your system has a more recent version of CUDA (e.g. 13.0) then these installation files may still work correctly. See the [Common Issues](#common-issues) section below if you are having trouble.
+
+If your system has an older version of CUDA, then there are several dependencies you may need to change: 
+- The PyTorch source: 
+    For example, if you have CUDA 12.4, 
+    ```bash
+    --extra-index-url https://download.pytorch.org/whl/cu128
+    --find-links https://data.pyg.org/whl/torch-2.8.0+cu128.html
+    ```
+    will become
+    ```bash
+    --extra-index-url https://download.pytorch.org/whl/cu124
+    --find-links https://data.pyg.org/whl/torch-2.6.0+cu124.html
+    ```
+    You can find the correct link to use [here](https://pytorch.org/get-started/previous-versions/). 
+- The torch version will need to be changed:
+    ```bash
+    torch==2.8.0+cu128
+    ```
+    would be come
+    ```bash
+    torch==2.6.0+cu124
+    ```
+    (As depicted in the example, you may have to change the torch version number depending on what is available for your CUDA version.)
+- You should then be able to remove the version numbers from the following dependencies: 
+    - nvidia-cublas-cu12
+    - nvidia-cuda-cupti-cu12
+    - nvidia-cuda-nvrtc-cu12
+    - nvidia-cuda-runtime-cu12
+    - nvidia-cudnn-cu12
+    - nvidia-cufft-cu12
+    - nvidia-cufile-cu12
+    - nvidia-curand-cu12
+    - nvidia-cusolver-cu12
+    - nvidia-cusparse-cu12
+    - nvidia-cusparselt-cu12
+    - nvidia-nccl-cu12
+    - nvidia-nvjitlink-cu12
+    - nvidia-nvtx-cu12 
+    - sympy
+    - torch-cluster
+    - torch-scatter
+- You may need to find a version of triton that works with your PyTorch/CUDA combination, or you might be able to remove the version requirement from the triton listing. For CUDA 12.4, `triton==3.2.0` works. 
+- 
+
+---
+(common-issues)=
+## Common Issues
+
+### `ImportError: /lib64/libm.so.6: version `GLIBC_2.27' not found`
+If you are seeing this, it is most likely because your CUDA version and the YAML or TOML file you are using to install the dependencies do not match. See [the previous section](#cuda_version) to modify your file for the CUDA version you have access to. 
+
+### `Segmentation Fault (core dumped)`
+This can be caused by a variety of different things, including a CUDA version mismatch. If you haven't already modified your TOML or YAML file, see [the previous section](#cuda_version).
+If you have updated these files, try adding the `dev` requirements to you installation instructions. 

env.yaml

@@ -1,4 +1,4 @@
-name: hbdesigner_debug
+name: hbdesigner
 channels:
   - conda-forge
 dependencies: