Skip to content

Commit 540d078

Browse files
rclunerclune
authored
Add and restructure documentation for RFdiffusion2 (#18)
Introduces new documentation files including installation instructions, overview, and links to README and license. Updates Sphinx configuration to include sphinx-copybutton and reorganizes index.rst for improved navigation. The GitHub workflow now installs sphinx-copybutton. README updated with a link to the documentation site.
1 parent cdf3707 commit 540d078

8 files changed

Lines changed: 210 additions & 47 deletions

File tree

‎.github/workflows/documentation_workflow.yml‎

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,27 @@
1-
name: documentation
2-
3-
on: [push, pull_request, workflow_dispatch]
4-
5-
permissions:
6-
contents: write
7-
8-
jobs:
9-
docs:
10-
runs-on: ubuntu-latest
11-
steps:
12-
- uses: actions/checkout@v4
13-
- uses: actions/setup-python@v5
14-
- name: Install dependencies
15-
run: |
16-
pip install sphinx sphinx_mdinclude furo
17-
- name: Sphinx build
18-
run: |
19-
sphinx-build -M html doc/source/ doc/build/
20-
- name: Deploy to GitHub Pages
21-
uses: peaceiris/actions-gh-pages@v3
22-
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
23-
with:
24-
publish_branch: gh-pages
25-
github_token: ${{ secrets.GITHUB_TOKEN }}
26-
publish_dir: doc/build/html
27-
force_orphan: true
1+
name: documentation
2+
3+
on: [push, pull_request, workflow_dispatch]
4+
5+
permissions:
6+
contents: write
7+
8+
jobs:
9+
docs:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-python@v5
14+
- name: Install dependencies
15+
run: |
16+
pip install sphinx sphinx_mdinclude furo sphinx-copybutton
17+
- name: Sphinx build
18+
run: |
19+
sphinx-build -M html doc/source/ doc/build/
20+
- name: Deploy to GitHub Pages
21+
uses: peaceiris/actions-gh-pages@v3
22+
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
23+
with:
24+
publish_branch: gh-pages
25+
github_token: ${{ secrets.GITHUB_TOKEN }}
26+
publish_dir: doc/build/html
27+
force_orphan: true

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ Open source code for RFdiffusion2 as described in the following pre-print.
1616
}
1717
```
1818

19+
More detailed information about how to run, install, and use RFdiffusion2 can be found [here](https://rosettacommons.github.io/RFdiffusion2/).
20+
1921
## Set-up
2022

2123
1. **Clone the repo.**

‎doc/source/conf.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@
1919
'sphinx.ext.autodoc',
2020
'sphinx.ext.napoleon',
2121
'sphinx_mdinclude',
22-
#'myst_parser', # to use markdown instead of ReST'
23-
22+
#'myst_parser', # to use markdown instead of ReST
23+
'sphinx_copybutton',
2424
]
2525

2626
#myst_enable_extensions = ["colon_fence"] # see https://mystmd.org/guide/syntax-overview for more information

‎doc/source/index.rst‎

Lines changed: 19 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,24 +3,25 @@
33
You can adapt this file completely to your liking, but it should at least
44
contain the root `toctree` directive.
55
6-
Welcome to the Official Documentation for RFdiffusion2!
7-
=======================================================
6+
Welcome to the Official Documentation for `RFdiffusion2 <https://github.com/RosettaCommons/RFdiffusion2>`_!
7+
===========================================================================================================
8+
.. mdinclude:: overview.md
89

910
.. toctree::
10-
:maxdepth: 2
11+
:maxdepth: 1
1112
:caption: Contents:
12-
13-
Indices and tables
14-
==================
15-
16-
* :ref:`genindex`
17-
* :ref:`modindex`
18-
* :ref:`search`
19-
20-
.. include:: new.rst
21-
22-
.. include:: modules.rst
23-
24-
.. mdinclude:: ../../README.md
25-
26-
13+
14+
Overview <self>
15+
readme_link.rst
16+
license_link.rst
17+
installation.md
18+
19+
.. Indices and tables
20+
.. ==================
21+
..
22+
.. * :ref:`genindex`
23+
.. * :ref:`modindex`
24+
.. * :ref:`search`
25+
..
26+
.. .. include:: new.rst
27+
.. .. include:: modules.rst

‎doc/source/installation.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Installing RFdiffusion2
2+
3+
## Apptainer Image (Recommended)
4+
There is an Apptainer image provided in the RFdiffusion2 repository, it is located at `RFdiffusion2/rf_diffusion/exec/bakerlab_rf_diffusion_aa.sif`. This file can be run with either Apptainer or Singularity, if you have any issues using it please [create an issue](https://github.com/RosettaCommons/RFdiffusion2/issues). An example of how to use this image is given in the [README](readme_link.html#inference).
5+
6+
If you need to generate your own image, the `.spec` file used to generate the given `.sif` file can be found at `RFdiffusion2/rf_diffusion/exec/rf_diffusion_aa.spec`.
7+
8+
## Installation from Source
9+
Some of the dependencies listed below will vary based on your system, especially the version of CUDA available on your cluster.
10+
You will likely need to change some of the versions of the tools below to successfully install RFdiffusion2.
11+
The instructions below are for CUDA 12.4 and PyTorch 2.4.
12+
For some useful troubleshooting tips, see the [Troubleshooting](#troubleshooting) section below.
13+
14+
1. Create a conda environment using [miniforge](https://github.com/conda-forge/miniforge) and activate it
15+
1. Point to the correct [NVIDIA-CUDA channel](https://anaconda.org/nvidia/cuda/labels), and install [PyTorch](https://pytorch.org/), Python 3.11, and [pip](https://pip.pypa.io/en/latest/) based on what is available on your system:
16+
```
17+
conda install --yes \
18+
-c nvidia/label/cuda-12.4.0 \
19+
-c https://conda.rosettacommons.org \
20+
-c pytorch \
21+
-c dglteam/label/th24_cu124 \
22+
python==3.11 \
23+
pip \
24+
numpy"<2" \
25+
matplotlib \
26+
jupyterlab \
27+
conda-forge::openbabel==3.1.1 \
28+
cuda \
29+
pytorch==2.4 \
30+
pytorch-cuda==12.4 \
31+
pyrosetta
32+
```
33+
> **REMEMBER:** You will need to change your CUDA version based on what is available on your system. This will need to be changed in the
34+
> NVIDIA channel, the dglteam channel, the pytorch version, and the pytorch-cuda version.
35+
36+
1. Use pip to install several Python libraries:
37+
```
38+
pip install \
39+
hydra-core==1.3.1 \
40+
ml-collections==0.1.1 \
41+
addict==2.4.0 \
42+
assertpy==1.1.0 \
43+
biopython==1.83 \
44+
colorlog \
45+
compact-json \
46+
cython==3.0.0 \
47+
cytoolz==0.12.3 \
48+
debugpy==1.8.5 \
49+
deepdiff==6.3.0 \
50+
dm-tree==0.1.8 \
51+
e3nn==0.5.1 \
52+
einops==0.7.0 \
53+
executing==2.0.0 \
54+
fastparquet==2024.5.0 \
55+
fire==0.6.0 \
56+
GPUtil==1.4.0 \
57+
icecream==2.1.3 \
58+
ipdb==0.13.11 \
59+
ipykernel==6.29.5 \
60+
ipython==8.27.0 \
61+
ipywidgets \
62+
mdtraj==1.10.0 \
63+
numba \
64+
omegaconf==2.3.0 \
65+
opt_einsum==3.3.0 \
66+
pandas==1.5.0 \
67+
plotly==5.16.1 \
68+
pre-commit==3.7.1 \
69+
py3Dmol==2.2.1 \
70+
pyarrow==17.0.0 \
71+
pydantic \
72+
pyrsistent==0.19.3 \
73+
pytest-benchmark \
74+
pytest-cov==4.1.0 \
75+
pytest-dotenv==0.5.2 \
76+
pytest==8.2.0 \
77+
rdkit==2024.3.5 \
78+
RestrictedPython \
79+
ruff==0.6.2 \
80+
scipy==1.13.1 \
81+
seaborn==0.13.2 \
82+
sympy==1.13.2 \
83+
tmtools \
84+
tqdm==4.65.0 \
85+
typer==0.12.5 \
86+
wandb==0.13.10
87+
```
88+
1. Install [Biotite](https://www.biotite-python.org/latest/index.html) and several libraries related to PyTorch, and [pylibcugraphops](https://pypi.org/project/pylibcugraphops-cu12/):
89+
```
90+
pip install biotite
91+
pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.4.0+cu124.html
92+
pip install -U -i https://pypi.anaconda.org/rapidsai-wheels-nightly/simple "pylibcugraphops-cu12>=24.6.0a24"
93+
```
94+
> **REMEMBER:** You will need to change the link for installing the PyTorch-related libraries (the second line in the code block above) to have it match your PyTorch and CUDA versions.
95+
1. Install a version of [TorchData](https://pypi.org/project/torchdata/#what-is-torchdata) that still has DataPipes:
96+
```
97+
pip install torchdata==0.9.0
98+
```
99+
1. Install a version of the [Deep Graph Library](https://www.dgl.ai/pages/start.html) based on the version of PyTorch and CUDA you are using:
100+
```
101+
conda install -c dglteam/label/th24_cu124 dgl
102+
```
103+
> **REMEMBER:** You will need to change the conda channel to the correct version of PyTorch (`th24` in the line above) and CUDA (`cu124` in the line above). Use the [Deep Graph Library's Installation guide](https://www.dgl.ai/pages/start.html) to determine the correct conda or pip command.
104+
1. Set your `PYTHONPATH` environment variable:
105+
```
106+
export PYTHONPATH=$PYTHONPATH:/path/to/RFdiffusion2
107+
```
108+
109+
.. _troubleshooting:
110+
111+
### Troubleshooting
112+
Ran into an installation issue not covered here? [Create a new issue!](https://github.com/RosettaCommons/RFdiffusion2/issues)
113+
114+
115+
<details>
116+
<summary>How to determine the highest available CUDA version on your system</summary>
117+
118+
The `nvidia-smi` command will print out information about the available GPUs you can access on your cluster.
119+
The first line in the result will look something like:
120+
```
121+
+---------------------------------------------------------------------------------------+
122+
| NVIDIA-SMI 535.230.02 Driver Version: 535.230.02 CUDA Version: 12.2 |
123+
|-----------------------------------------+----------------------+----------------------+
124+
```
125+
Here, this means that this system can only support up to CUDA 12.2. However, if you look at the possible [PyTorch versions](https://pytorch.org/get-started/previous-versions/)
126+
and [Deep Graph Library versions](https://www.dgl.ai/pages/start.html) on their installation pages, you'll notice that they don't
127+
have versions for 12.2, so in this situation you would need to change the installation instructions to work with CUDA 12.1.
128+
</details>
129+
130+
<details>
131+
<summary>Cannot find DGL C++ graphbolt library at...</summary>
132+
133+
Seeing this error likely means that the version of the Deep Graph Library (DGL) that you have installed does not match
134+
the corresponding version of PyTorch your system is finding. Double check that you installed the correct versions of
135+
these tools and ensure that your system does not have a different version of PyTorch it is finding.
136+
137+
It might also be useful to `ls` in the given directory to see what version of the DGL libraries you have installed.
138+
For example, if your error says it is looking for `graphbolt/libgraphbolt_pytorch_2.4.0.so` it means your system is
139+
using Pytorch version 2.4.0. Meanwhile if you `ls` in the directory you might see that you only have `libgraphbolt_pytorch_2.1.2.so`
140+
meaning that the version of DGL you downloaded was only mean to work with PyTorch versions up to 2.1.2.
141+
</details>
142+
143+
<details>
144+
<summary>No module named 'torchdata.datapipes'</summary>
145+
146+
Newer versions of TorchData have stopped supporting their DataPipes tools. You will need to downgrade the version of TorchData
147+
you have installed to one at or below version 0.9.0. You can learn more about this change on [TorchData's PyPI page](https://pypi.org/project/torchdata/).
148+
</details>
149+
150+

‎doc/source/license_link.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
LICENSE
2+
#######
3+
.. mdinclude:: ../../LICENSE.md

‎doc/source/overview.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Overview
2+
========
3+
4+
RFdiffusion2 is a

‎doc/source/readme_link.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
README
2+
######
3+
.. mdinclude:: ../../README.md

0 commit comments

Comments
 (0)