Skip to content

Commit 9bbe971

Browse files
rclunerclune
committed
Add and restructure documentation for RFdiffusion2
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 952546b commit 9bbe971

File tree

8 files changed

+210
-47
lines changed

8 files changed

+210
-47
lines changed

‎.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)