Revise docs and environments for improved setup

Updated documentation to improve clarity and navigation, including new Sphinx includes for README, LICENSE, and CONTRIBUTING. Added a dedicated installation guide and macOS environment file. Removed obsolete environment files and Apptainer spec, streamlining environment setup instructions to favor provided YAML files and external documentation.

Author: rclune

CONTRIBUTING.md

@@ -27,6 +27,8 @@ When contributing to the code base, please adhere to the [PEP8 style guide](http
 Please write tests for any contributed code or append to 
 existing tests.
 
+Existing tests can be found in `rf_diffusion/test_inference_commands.py`
+
 ### Approving and Merging Pull Requests
 Currently only the original developers and the Devel Team 
 at Rosetta Commons can approve and merge pull requests. PRs

README.md

@@ -12,15 +12,22 @@ This repository contains the code for the [associated preprint](https://www.bior
   publisher={Cold Spring Harbor Laboratory}
 }
 ```
+## Documentation
+More information and documentation can be found [here](https://rosettacommons.github.io/RFDpoly/).
 
 ## Installation and setup
 
-0. Clone the repository 
+### 1. Clone the repository 
 ```bash
 git clone [email protected]:RosettaCommons/RFDpoly.git
 ```
 
-1. Set environment variables and create directories 
+### 2. Set environment variables and create directories 
+
+*This section is not necessary for running RFDpoly,
+but te example commands below use these environment
+variables.*
+
 
 Set relevant paths for installation and then create the directories the paths point to:
 
@@ -38,7 +45,7 @@ mkdir -p $WEIGHTS_DIR
 mkdir -p $ENV_DIR
 ```
 
-3. Navigate to the directory where you want to save model weights, download them, and set path variable for weights of your choice:
+### 3. Navigate to the directory where you want to save model weights, download them, and set path variable for weights of your choice:
 ```Bash
 # Download model weights:
 cd $WEIGHTS_DIR
@@ -52,7 +59,7 @@ curl -O https://files.ipd.uw.edu/pub/2025_RFDpoly/train_session2024-07-08_172045
 export RFDPOLY_CKPT_PATH=\$WEIGHTS_DIR/train_session2024-07-08_1720455712_BFF_3.00.pt
 ```
 
-4. Setting up the environment:
+### 4. Setting up the environment:
 Navigate to the directory where you want to [Apptainer](https://apptainer.org/) file, download it, and set path variable:
 ```Bash
 cd $ENV_DIR
@@ -61,10 +68,8 @@ APPTAINER_PATH=$ENV_DIR/SE3nv.sif
 ```
 Downloading the `.sif` file may take several minutes. 
 
-<!--Equivalent python environments can be set up using [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html), or an environment manager of your choice. Environment files are provided in `rf_diffusion/environment` and can be used as follows:
-```bash
-apptainer build SE3nv.sif SE
-```-->
+You can find alternative installation instructions in the
+[external documentation](https://rosettacommons.github.io/RFDpoly/).
 
 ## Basic Use Case Example: Testing Your Setup
 
@@ -125,10 +130,8 @@ Contact **[email protected]** if you have trouble accessing files or hit any bugs.
   - Primary workflow: Linux host with [Apptainer](https://apptainer.org/) ≥ 1.1 (or Singularity equivalent). The bundled container image runs Ubuntu 22.04.2 LTS.
   - Alternative workflow: macOS 13+/Windows 11 via Conda (CPU only unless you install CUDA-capable PyTorch wheels).
 - **Software dependencies**
-  - Apptainer runtime to execute `SE3nv.sif`, this can be built from `SE3nv.spec` in `rf_diffusion/environment`
   - For native/Conda installs: Python 3.10, PyTorch 1.13.1, CUDA 11.7 toolchain (if using an NVIDIA GPU), PyRosetta 2023.09+, DGL 1.0.1, e3nn 0.5.1, hydra-core 1.3.2, and the packages listed in `rf_diffusion/environment/environment.yml`.
   - **NOTE:** All dependencies are specified in `rf_diffusion/environment/`, such that users can set up an equivalent working environment on any operating system.
-  - Downloaded assets: model checkpoints (`*.pt`, ~2.3 GB each) and the container image (`SE3nv.sif`, ~8 GB).
 - **Tested configurations**
   - Ubuntu 22.04 host with Apptainer 1.1.9, NVIDIA driver ≥ 515, CUDA 11.7 runtime.
   - PyTorch 1.13.1+cu117, Python 3.10.8, PyRosetta 2023.09 inside the container.

docs/source/conf.py

@@ -32,7 +32,7 @@
 
 html_theme_options = {
     "sidebar_hide_name":False,
-    "announcement": "<em>THIS DOCUMENTATION IS CURRENTLY UNDER CONSTRUCTION</em>",
+    #"announcement": "<em>THIS DOCUMENTATION IS CURRENTLY UNDER CONSTRUCTION</em>",
     "light_css_variables": {
         "color-brand-primary": "#F68A33", # Rosetta Teal
         "color-brand-content": "#37939B", # Rosetta Orange

docs/source/contributing_link.rst

@@ -0,0 +1,5 @@
+CONTRIBUTING to RFDpoly
+=======================                                                                                        
+
+.. include:: ../../CONTRIBUTING.md
+   :parser: myst_parser.sphinx_

docs/source/index.rst

@@ -6,12 +6,15 @@
 RFDpoly documentation
 =====================
 
-Add your content using ``reStructuredText`` syntax. See the
-`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-documentation for details.
+.. include:: readme_link.rst
 
 
 .. toctree::
-   :maxdepth: 2
+   :titlesonly:
    :caption: Contents:
 
+   readme_link.rst<self>
+   license_link.rst
+   contributing_link.rst
+   installation_guide.md
+

docs/source/installation_guide.md

@@ -0,0 +1,92 @@
+# Installation Guide
+
+## Using the Apptainer Image
+If possible, we highly recommend using the provided apptainer image which can be obtained via:
+```bash
+curl -O https://files.ipd.uw.edu/pub/2025_RFDpoly/SE3nv.sif
+```
+
+Here is an example for how to use this image to run RFDpoly: 
+```bash
+apptainer run --nv /path/to/SE3nv.sif /path/to/RFDpoly/rf_diffusion/run_inference.py --config-name=multi_polymer \
+diffuser.T=50 \
+inference.ckpt_path=/path/to/train_session2024-07-08_1720455712_BFF_3.00.pt \
+inference.num_designs=1 \
+contigmap.contigs=[\'33\ 33\ 75\'] \
+contigmap.polymer_chains=[\'dna\',\'rna\',\'protein\'] \
+inference.output_prefix=/path/to/your/output/directory/basic_uncond_test01
+```
+
+If you see an error when attempting to run this related to
+a lack of an input file, try adding this option:
+```bash
+inference.input_pdb=/path/to/RFDpoly/rf_diffusion/test_data/DBP035.pdb
+```
+
+## Creating a Conda Environment
+
+### Linux: 
+If the apptainer image is not compatible with your system
+or you are doing development with RFDpoly, you can create
+a [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) or [mamba](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html) environment with a provided `environment.yml` file: 
+
+```bash
+conda env create -f /path/to/RFDpoly/rf_diffusion/environment/environment.yml
+conda activate RFDpoly_env
+pip install /path/to/RFDpoly/rf_diffusion/RF2-allatom/rf2aa/SE3Transformer
+```
+The last command installs a slightly modified version of 
+se3-transformer. If installing this package does not work,
+you can try installing [`se3-transformer-pytorch`](https://pypi.org/project/se3-transformer-pytorch/) instead,
+but we do not guarantee that your results will be exactly
+the same. 
+
+You can test your installation by running: 
+```bash
+python /path/to/RFDpoly/rf_diffusion/run_inference.py \
+--config-name=multi_polymer \
+diffuser.T=50 \
+inference.ckpt_path=/path/to/RFDpoly/weights/train_session2024-07-08_1720455712_BFF_3.00.pt \
+inference.num_designs=1 \
+contigmap.contigs=[\'33\ 33\ 75\'] \
+contigmap.polymer_chains=[\'dna\',\'rna\',\'protein\'] \
+inference.output_prefix=./basic_uncond_test01
+```
+
+If using the `environment.yml` file does not work, please
+create an issue. Or, if you modified the `.yml` file to 
+work for your system, make a pull request to add it to 
+the `rf_diffusion/environment` folder. 
+
+### MacOS
+If the apptainer image is not compatible with your system
+or you are doing development with RFDpoly, you can create
+a [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) or [mamba](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html) environment with a provided `macos_environment.yml` file: 
+
+```bash
+conda env create -f /path/to/RFDpoly/rf_diffusion/environment/macos_environment.yml
+conda activate RFDpoly_env
+pip install /path/to/RFDpoly/rf_diffusion/RF2-allatom/rf2aa/SE3Transformer
+```
+The last command installs a slightly modified version of 
+se3-transformer. If installing this package does not work,
+you can try installing [`se3-transformer-pytorch`](https://pypi.org/project/se3-transformer-pytorch/) instead,
+but we do not guarantee that your results will be exactly
+the same. 
+
+You can test your installation by running: 
+```bash
+python /path/to/RFDpoly/rf_diffusion/run_inference.py \
+--config-name=multi_polymer \
+diffuser.T=50 \
+inference.ckpt_path=/path/to/RFDpoly/weights/train_session2024-07-08_1720455712_BFF_3.00.pt \
+inference.num_designs=1 \
+contigmap.contigs=[\'33\ 33\ 75\'] \
+contigmap.polymer_chains=[\'dna\',\'rna\',\'protein\'] \
+inference.output_prefix=./basic_uncond_test01
+```
+
+If using the `macos_environment.yml` file does not work, 
+please create an issue. Or, if you modified the `.yml` file 
+to work for your system, make a pull request to add it to 
+the `rf_diffusion/environment` folder. 

docs/source/license_link.rst

@@ -0,0 +1,5 @@
+LICENSE
+=======                                                                                                 
+
+.. include:: ../../LICENSE.md
+   :parser: myst_parser.sphinx_

docs/source/readme_link.rst

@@ -0,0 +1,6 @@
+README
+======                                                                                                 
+
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+