From 6001035d821c073f261d4ff6793e2644f6d24e56 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 11 Aug 2025 09:24:43 +0000 Subject: [PATCH] Restructure documentation with comprehensive API reference and guides Co-authored-by: yaoyy --- docs/api.rst | 8 +++++ docs/api/rosettapy.analyser.rst | 28 +++++++++++++++ docs/api/rosettapy.app.rst | 22 ++++++++++++ docs/api/rosettapy.common.rst | 35 ++++++++++++++++++ docs/api/rosettapy.node.rst | 35 ++++++++++++++++++ docs/api/rosettapy.rosetta.rst | 16 +++++++++ docs/api/rosettapy.rosetta_finder.rst | 16 +++++++++ docs/api/rosettapy.rst | 21 +++++++++++ docs/api/rosettapy.utils.rst | 34 ++++++++++++++++++ docs/conf.py | 30 ++++++++++++++++ docs/getting-started.rst | 52 +++++++++++++++++++++++++++ docs/guides.rst | 14 ++++++++ docs/guides/cart_ddg.rst | 23 ++++++++++++ docs/guides/fastrelax.rst | 18 ++++++++++ docs/guides/mutate_relax.rst | 23 ++++++++++++ docs/guides/pross.rst | 29 +++++++++++++++ docs/guides/rosettaligand.rst | 19 ++++++++++ docs/guides/supercharge.rst | 18 ++++++++++ docs/index.rst | 5 ++- docs/modules.rst | 7 +--- docs/requirements.txt | 1 + 21 files changed, 447 insertions(+), 7 deletions(-) create mode 100644 docs/api.rst create mode 100644 docs/api/rosettapy.analyser.rst create mode 100644 docs/api/rosettapy.app.rst create mode 100644 docs/api/rosettapy.common.rst create mode 100644 docs/api/rosettapy.node.rst create mode 100644 docs/api/rosettapy.rosetta.rst create mode 100644 docs/api/rosettapy.rosetta_finder.rst create mode 100644 docs/api/rosettapy.rst create mode 100644 docs/api/rosettapy.utils.rst create mode 100644 docs/getting-started.rst create mode 100644 docs/guides.rst create mode 100644 docs/guides/cart_ddg.rst create mode 100644 docs/guides/fastrelax.rst create mode 100644 docs/guides/mutate_relax.rst create mode 100644 docs/guides/pross.rst create mode 100644 docs/guides/rosettaligand.rst create mode 100644 docs/guides/supercharge.rst diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..4a1d68d --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,8 @@ +RosettaPy API Reference +======================== + +.. toctree:: + :maxdepth: 2 + :caption: Packages + + api/rosettapy \ No newline at end of file diff --git a/docs/api/rosettapy.analyser.rst b/docs/api/rosettapy.analyser.rst new file mode 100644 index 0000000..6692bff --- /dev/null +++ b/docs/api/rosettapy.analyser.rst @@ -0,0 +1,28 @@ +RosettaPy.analyser +=================== + +.. automodule:: RosettaPy.analyser + :members: + :undoc-members: + :show-inheritance: + +Modules +------- + +.. autosummary:: + :toctree: generated + :recursive: + + RosettaPy.analyser.ddg + RosettaPy.analyser.reu + +Key Classes +----------- + +.. autoclass:: RosettaPy.analyser.RosettaEnergyUnitAnalyser + :members: + :show-inheritance: + +.. autoclass:: RosettaPy.analyser.RosettaCartesianddGAnalyser + :members: + :show-inheritance: \ No newline at end of file diff --git a/docs/api/rosettapy.app.rst b/docs/api/rosettapy.app.rst new file mode 100644 index 0000000..488a9c2 --- /dev/null +++ b/docs/api/rosettapy.app.rst @@ -0,0 +1,22 @@ +RosettaPy.app +============== + +.. automodule:: RosettaPy.app + :members: + :undoc-members: + :show-inheritance: + +Modules +------- + +.. autosummary:: + :toctree: generated + :recursive: + + RosettaPy.app.cart_ddg + RosettaPy.app.fastrelax + RosettaPy.app.mutate_relax + RosettaPy.app.pross + RosettaPy.app.rosettaligand + RosettaPy.app.utils.CA_constraints + RosettaPy.app.utils.smiles2param \ No newline at end of file diff --git a/docs/api/rosettapy.common.rst b/docs/api/rosettapy.common.rst new file mode 100644 index 0000000..17ac7cc --- /dev/null +++ b/docs/api/rosettapy.common.rst @@ -0,0 +1,35 @@ +RosettaPy.common +================= + +.. automodule:: RosettaPy.common + :members: + :undoc-members: + :show-inheritance: + +Modules +------- + +.. autosummary:: + :toctree: generated + :recursive: + + RosettaPy.common.mutation + +Key Classes +----------- + +.. autoclass:: RosettaPy.common.mutation.Mutation + :members: + :show-inheritance: + +.. autoclass:: RosettaPy.common.mutation.Chain + :members: + :show-inheritance: + +.. autoclass:: RosettaPy.common.mutation.RosettaPyProteinSequence + :members: + :show-inheritance: + +.. autoclass:: RosettaPy.common.mutation.Mutant + :members: + :show-inheritance: \ No newline at end of file diff --git a/docs/api/rosettapy.node.rst b/docs/api/rosettapy.node.rst new file mode 100644 index 0000000..4a57d39 --- /dev/null +++ b/docs/api/rosettapy.node.rst @@ -0,0 +1,35 @@ +RosettaPy.node +=============== + +.. automodule:: RosettaPy.node + :members: + :undoc-members: + :show-inheritance: + +Modules +------- + +.. autosummary:: + :toctree: generated + :recursive: + + RosettaPy.node.dockerized + RosettaPy.node.mpi + RosettaPy.node.native + RosettaPy.node.utils + RosettaPy.node.wsl + +Key Classes +----------- + +.. autoclass:: RosettaPy.node.MpiNode + :members: + +.. autoclass:: RosettaPy.node.Native + :members: + +.. autoclass:: RosettaPy.node.WslWrapper + :members: + +.. autoclass:: RosettaPy.node.dockerized.RosettaContainer + :members: \ No newline at end of file diff --git a/docs/api/rosettapy.rosetta.rst b/docs/api/rosettapy.rosetta.rst new file mode 100644 index 0000000..a4be1cf --- /dev/null +++ b/docs/api/rosettapy.rosetta.rst @@ -0,0 +1,16 @@ +RosettaPy.rosetta +================== + +.. automodule:: RosettaPy.rosetta + :members: + :undoc-members: + :show-inheritance: + +Key Classes +----------- + +.. autoclass:: RosettaPy.rosetta.Rosetta + :members: + +.. autoclass:: RosettaPy.rosetta.RosettaScriptsVariableGroup + :members: \ No newline at end of file diff --git a/docs/api/rosettapy.rosetta_finder.rst b/docs/api/rosettapy.rosetta_finder.rst new file mode 100644 index 0000000..d3e451d --- /dev/null +++ b/docs/api/rosettapy.rosetta_finder.rst @@ -0,0 +1,16 @@ +RosettaPy.rosetta_finder +========================= + +.. automodule:: RosettaPy.rosetta_finder + :members: + :undoc-members: + :show-inheritance: + +Key Classes +----------- + +.. autoclass:: RosettaPy.rosetta_finder.RosettaBinary + :members: + +.. autoclass:: RosettaPy.rosetta_finder.RosettaFinder + :members: \ No newline at end of file diff --git a/docs/api/rosettapy.rst b/docs/api/rosettapy.rst new file mode 100644 index 0000000..fc5160d --- /dev/null +++ b/docs/api/rosettapy.rst @@ -0,0 +1,21 @@ +RosettaPy Package +================= + +.. automodule:: RosettaPy + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + :maxdepth: 1 + + rosettapy.analyser + rosettapy.app + rosettapy.common + rosettapy.node + rosettapy.utils + rosettapy.rosetta + rosettapy.rosetta_finder \ No newline at end of file diff --git a/docs/api/rosettapy.utils.rst b/docs/api/rosettapy.utils.rst new file mode 100644 index 0000000..652b8e8 --- /dev/null +++ b/docs/api/rosettapy.utils.rst @@ -0,0 +1,34 @@ +RosettaPy.utils +================ + +.. automodule:: RosettaPy.utils + :members: + :undoc-members: + :show-inheritance: + +Modules +------- + +.. autosummary:: + :toctree: generated + :recursive: + + RosettaPy.utils.escape + RosettaPy.utils.repository + RosettaPy.utils.task + RosettaPy.utils.tools + +Key Items +--------- + +.. autofunction:: RosettaPy.utils.render + +.. autofunction:: RosettaPy.utils.print_diff + +.. autofunction:: RosettaPy.utils.zip_render + +.. autoclass:: RosettaPy.utils.RosettaCmdTask + :members: + +.. autoclass:: RosettaPy.utils.RosettaScriptsVariableGroup + :members: \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 4867d95..f634a0a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,12 +33,42 @@ # ones. extensions = [ "sphinx.ext.autodoc", + "sphinx.ext.autosummary", "sphinx.ext.doctest", "sphinx.ext.intersphinx", "sphinx.ext.ifconfig", "sphinx.ext.viewcode", # Add links to highlighted source code "sphinx.ext.napoleon", # to render Google format docstrings "sphinx.ext.githubpages", + "sphinx_copybutton", +] + +# Autosummary settings +autosummary_generate = True + +# Autodoc defaults +autodoc_default_options = { + "members": True, + "undoc-members": True, + "show-inheritance": True, + "inherited-members": True, +} + +# Display type hints in the description +autodoc_typehints = "description" + +# Mock heavy/optional third-party deps during doc build +autodoc_mock_imports = [ + "Bio", + "pandas", + "numpy", + "matplotlib", + "docker", + "git", + "rdkit", + "joblib", + "joblib_progress", + "tree", ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/getting-started.rst b/docs/getting-started.rst new file mode 100644 index 0000000..6a5989a --- /dev/null +++ b/docs/getting-started.rst @@ -0,0 +1,52 @@ +Getting Started +=============== + +Installation +------------ + +.. code-block:: bash + + pip install RosettaPy -U + +Prerequisites +------------- + +- Rosetta must be compiled and installed with a valid license. +- Ensure the `rosetta_scripts` binary is available locally or in a supported container. + +Minimal Example +--------------- + +.. code-block:: python + + import os + from RosettaPy import Rosetta, RosettaScriptsVariableGroup + from RosettaPy.node import node_picker + + rosetta = Rosetta( + bin="rosetta_scripts", + flags=["/path/to/flags.txt"], + opts=["-in:file:s", "/path/to/input.pdb", "-parser:protocol", "/path/to/protocol.xml"], + output_dir="./outputs", + job_id="demo", + run_node=node_picker("native"), + verbose=False, + ) + + # Optional: supply RosettaScripts variables + rsv = RosettaScriptsVariableGroup.from_dict({ + "TASKOPERATIONS": ["OperateOnCertainResidues"], + }) + + rosetta.opts.append(rsv) + tasks = rosetta.run(nstruct=2) + + # Each task contains the composed command; running returns execution results + for t in tasks: + print(t.cmd) + +Where to go next +---------------- + +- See the guides for specific workflows like PROSS, FastRelax, RosettaLigand, Supercharge, MutateRelax, and Cartesian ddG. +- Explore the full API reference for classes and functions. \ No newline at end of file diff --git a/docs/guides.rst b/docs/guides.rst new file mode 100644 index 0000000..9e58508 --- /dev/null +++ b/docs/guides.rst @@ -0,0 +1,14 @@ +Guides +====== + +This section provides end-to-end examples for common tasks. + +.. toctree:: + :maxdepth: 1 + + guides/pross + guides/fastrelax + guides/rosettaligand + guides/supercharge + guides/mutate_relax + guides/cart_ddg \ No newline at end of file diff --git a/docs/guides/cart_ddg.rst b/docs/guides/cart_ddg.rst new file mode 100644 index 0000000..77f613d --- /dev/null +++ b/docs/guides/cart_ddg.rst @@ -0,0 +1,23 @@ +Cartesian ddG Workflow +====================== + +Example +------- + +.. code-block:: python + + from RosettaPy.app.cart_ddg import CartesianddG + from RosettaPy.common.mutation import Mutant, Mutation, RosettaPyProteinSequence, Chain + from RosettaPy.node import node_picker + + wt = RosettaPyProteinSequence(chains=[Chain(chain_id="A", sequence="IRGWEEGVAQM")]) + mutant = Mutant(mutations=[Mutation(chain_id="A", position=10, wt_res="Q", mut_res="V")], wt_protein_sequence=wt) + + app = CartesianddG( + pdb="/path/to/wt.pdb", + mutant=mutant, + output_dir="./outputs", + node=node_picker("native"), + ) + ddg = app.run(nstruct=25) + print(ddg) \ No newline at end of file diff --git a/docs/guides/fastrelax.rst b/docs/guides/fastrelax.rst new file mode 100644 index 0000000..9cdd0b5 --- /dev/null +++ b/docs/guides/fastrelax.rst @@ -0,0 +1,18 @@ +FastRelax Workflow +================== + +Example +------- + +.. code-block:: python + + from RosettaPy.app.fastrelax import FastRelax + from RosettaPy.node import node_picker + + fr = FastRelax( + pdb="/path/to/input.pdb", + output_dir="./outputs", + node=node_picker("native"), + ) + scores = fr.run(nstruct=10) + print(scores.describe()) \ No newline at end of file diff --git a/docs/guides/mutate_relax.rst b/docs/guides/mutate_relax.rst new file mode 100644 index 0000000..df0cbc7 --- /dev/null +++ b/docs/guides/mutate_relax.rst @@ -0,0 +1,23 @@ +MutateRelax Workflow +==================== + +Example +------- + +.. code-block:: python + + from RosettaPy.app.mutate_relax import MutateRelax + from RosettaPy.common.mutation import Mutant, Mutation, RosettaPyProteinSequence, Chain + from RosettaPy.node import node_picker + + wt = RosettaPyProteinSequence(chains=[Chain(chain_id="A", sequence="IRGWEEGVAQM")]) + mutant = Mutant(mutations=[Mutation(chain_id="A", position=10, wt_res="Q", mut_res="V")], wt_protein_sequence=wt) + + mr = MutateRelax( + pdb="/path/to/wt.pdb", + mutant=mutant, + output_dir="./outputs", + node=node_picker("native"), + ) + df = mr.run(nstruct=10) + print(df.head()) \ No newline at end of file diff --git a/docs/guides/pross.rst b/docs/guides/pross.rst new file mode 100644 index 0000000..55e3dda --- /dev/null +++ b/docs/guides/pross.rst @@ -0,0 +1,29 @@ +PROSS Workflow +============== + +The PROSS application designs stabilizing mutations using RosettaScripts. + +Example +------- + +.. code-block:: python + + import os + from RosettaPy.app.pross import PROSS + from RosettaPy.node import node_picker + + workflow = PROSS( + pdb="/path/to/input.pdb", + seqres="/path/to/seqres.fasta", # optional + output_dir="./outputs", + node=node_picker("native"), + ) + + # Run design; returns analysis results and artifacts in output_dir + df = workflow.run(nstruct=5) + print(df.head()) + +Notes +----- +- Requires a working `rosetta_scripts` and access to the provided protocol in the package. +- See API docs for configurable parameters. \ No newline at end of file diff --git a/docs/guides/rosettaligand.rst b/docs/guides/rosettaligand.rst new file mode 100644 index 0000000..a9db280 --- /dev/null +++ b/docs/guides/rosettaligand.rst @@ -0,0 +1,19 @@ +RosettaLigand Workflow +====================== + +Example +------- + +.. code-block:: python + + from RosettaPy.app.rosettaligand import RosettaLigand + from RosettaPy.node import node_picker + + rl = RosettaLigand( + receptor_pdb="/path/to/receptor.pdb", + ligand_params="/path/to/ligand.params", + output_dir="./outputs", + node=node_picker("native"), + ) + scores = rl.run(nstruct=20) + print(scores.sort_values("total_score").head()) \ No newline at end of file diff --git a/docs/guides/supercharge.rst b/docs/guides/supercharge.rst new file mode 100644 index 0000000..950a119 --- /dev/null +++ b/docs/guides/supercharge.rst @@ -0,0 +1,18 @@ +Supercharge Workflow +==================== + +Example +------- + +.. code-block:: python + + from RosettaPy.app.supercharge import supercharge + from RosettaPy.node import node_picker + + scores = supercharge( + pdb="/path/to/input.pdb", + target_pI=9.0, + output_dir="./outputs", + node=node_picker("native"), + ) + print(scores.head()) \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index b10c570..7508445 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,7 +9,10 @@ Welcome to ai-python docs's documentation! .. toctree:: :maxdepth: 2 :caption: Contents: - modules + + getting-started + guides + api Indices and tables diff --git a/docs/modules.rst b/docs/modules.rst index 8feff2b..3ce0218 100644 --- a/docs/modules.rst +++ b/docs/modules.rst @@ -1,7 +1,2 @@ -src -=== +.. This file is replaced by the new API reference structure. -.. toctree:: - :maxdepth: 4 - - python_package diff --git a/docs/requirements.txt b/docs/requirements.txt index b75b86b..214f4e8 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ sphinx sphinx-copybutton sphinx-rtd-theme +sphinx-autobuild