Merge pull request #344 from rwxayheee/update_doc

Some updates to documentation

.gitignore

@@ -1,3 +1,4 @@
+*.DS_Store
 *.o
 build/python/vina/autodock_vina_wrap.cpp
 build/python/vina/vina_wrapper.py

docs/source/colab_examples.rst

@@ -0,0 +1,57 @@
+.. _colab_examples:
+
+Colab Examples
+============
+
+`Google Colaboratory <https://colab.google/>`_ (Colab) is a cloud-based platform that allows users to write and execute Python codes through a browser. Regardless of the user's operating system, Colab provides Linux computing backends and some free GPU access. 
+
+The following Colab examples are created to provide **an install-free experience** & **some generalizable workflows** of AutoDock Vina via Google Colab notebooks, which work in a similar manner to `Jupyter Notebooks <https://jupyter.org/>`_, in the pre-configured environment with `Meeko <https://github.com/forlilab/Meeko>`_ for receptor and ligand preparation, and other modules - `RDKit <https://rdkit.org/>`_, `Scrubber <https://github.com/forlilab/scrubber>`_, `ProDy <http://www.bahargroup.org/prody/>`_, `reduce2 <https://github.com/cctbx/cctbx_project/tree/master/mmtbx/reduce#reduce2>`_ (formerly `reduce <https://github.com/rlabduke/reduce>`_), and `py3Dmol <https://github.com/avirshup/py3dmol>`_ - for conformer generation, manipulation & pre-processing of protein structures and visualization. 
+
+**Subscription is NOT required to run these Colab examples.** Additionally, the input files for the docking calculations are either directly pulled from open databases or generated from user inputs. With that, one can easily customize the notebooks and reuse the workflow for similar calculations on different biochemical systems. 
+
+Overview
+------------------------
+
+**General Workflow of Docking Calculations in Examples**
+
+.. image:: images/docking_workflow.png
+   :alt: docking workflow
+   :width: 100%
+   :align: center
+
+*Major Python packages used* 
+
+* **RDKit** `https://rdkit.org/ <https://rdkit.org/>`_ 
+* **Scrubber** `https://github.com/forlilab/scrubber <https://github.com/forlilab/scrubber>`_ 
+* **Meeko** `https://github.com/forlilab/Meeko <https://github.com/forlilab/Meeko>`_ 
+* **ProDy** `http://www.bahargroup.org/prody/ <http://www.bahargroup.org/prody/>`_ 
+* **cctbx-base** (for reduce2) `https://github.com/cctbx/cctbx_project <https://github.com/cctbx/cctbx_project>`_ 
+* **py3Dmol** `https://3dmol.org/ <https://3dmol.org/>`_ 
+
+*Data* 
+
+* **Phenix-project/geostd** (for reduce2) `https://github.com/phenix-project/geostd/ <https://github.com/phenix-project/geostd/>`_ 
+
+Basic docking
+------------------------
+
+`Run on Colab! <https://colab.research.google.com/drive/1cHSl78lBPUc_J1IZxLgN4GwD_ADmohVU?usp=sharing>`_
+
+The **basic docking example** is a rewrite based on the original basic docking example. In this example, a small molecule ligand (Imatinib, PDB token `STI <https://www1.rcsb.org/ligand/STI>`_) is docked back to a hollow protein structure of mouse c-Abl (PDB token `1IEP <https://www1.rcsb.org/structure/1IEP>`_) to reproduce the complex structure. A docked pose that closely resembles the original position of the ligand is expected among the top-ranked poses. 
+
+
+Flexible docking
+------
+
+`Run on Colab! <https://colab.research.google.com/drive/1cazEckGbvl9huWzpxXpd_Qaj0_NipWcz?usp=sharing>`_
+
+The **flexible docking example** is a rewrite based on the original flexible docking example. In this example, a variant of Imatinib (PDB token `PRC <https://www1.rcsb.org/ligand/PRC>`_) is docked back to a hollow protein structure of mouse c-Abl (PDB token `1FPU <https://www1.rcsb.org/structure/1FPU>`_) to reproduce the complex structure. Additionally, Thr315 is set to be a flexible residue. A docked pose that closely resembles the original position of the ligand and **a flipped Thr315** are expected among the top-ranked poses. 
+
+
+Using AD4SF in Vina
+---------------
+
+`Run on Colab! <https://colab.research.google.com/drive/1zoSyID2fSoqGz3Zb1_IatUT2uxZ2mCNZ?usp=sharing>`_
+
+The **using AutoDock4 (AD4) scoring function (SF) example** is a rewrite based on the corresponding part of the original basic docking example. This example conducts the same redocking experiment as in *Basic docking* with the AutoDock4 scoring function instead of Vina. To do this, Autogrid4 is used to compute the grid maps, as an additional step after receptor preparation. 
+

docs/source/docking_basic.rst

@@ -22,7 +22,7 @@ For this tutorial, all the basic material are provided and can be found in the `
 1. Preparing the receptor
 -------------------------
 
-During this step, we will create a PDBQT file of our receptor containing only the polar hydrogen atoms as well as partial charges. For this step, we will use the ``prepare_receptor`` command tool from the ADFR Suite. As a prerequisite, a receptor coordinate file must contain all hydrogen atoms. If hydrogen atoms are absent in the protein structure file, you can add the ``-A "hydrogens"`` flag. Many tools exist to add missing hydrogen atoms to a protein, one popular choice would be to use `REDUCE <http://kinemage.biochem.duke.edu/software/reduce.php>`_. If you are using experimental structures (for instance, from the `Protein Data Bank <https://www.rcsb.org>`_), use a text editor to remove waters, ligands, cofactors, ions deemed unnecessary for the docking. This file contains the receptor coordinates taken from PDB entry `1iep <https://www.rcsb.org/structure/1IEP>`_.
+During this step, we will create a PDBQT file of our receptor containing only the polar hydrogen atoms as well as partial charges. For this step, we will use the ``prepare_receptor`` command tool from the ADFR Suite. As a prerequisite, a receptor coordinate file must contain all hydrogen atoms. If hydrogen atoms are absent in the protein structure file, you can add the ``-A "hydrogens"`` flag. Many tools exist to add missing hydrogen atoms to a protein, one popular choice would be to use `REDUCE <https://github.com/rlabduke/reduce>`_. If you are using experimental structures (for instance, from the `Protein Data Bank <https://www.rcsb.org>`_), use a text editor to remove waters, ligands, cofactors, ions deemed unnecessary for the docking. This file contains the receptor coordinates taken from PDB entry `1iep <https://www.rcsb.org/structure/1IEP>`_.
 
 .. code-block:: bash
 

docs/source/docking_requirements.rst

@@ -3,52 +3,24 @@
 Software requirements
 =====================
 
-For those tutorials, the ADFR software suite, providing a number of software tools for automated docking and peripheral tasks, and the Python package Raccoon-lite, for preparing macrocycle for example, are necessary.
+In addition to AutoDockTools, the long standing GUI for docking calculation setup and management, the following helper tools are developed at the `Center for Computational Structural Biology (CCSB) <https://ccsb.scripps.edu>`_ and can be used for docking input preparation. 
 
-ADFR software suite
--------------------
-
-.. warning::
-
-    macOS users please note that ADFR software suite is NOT working under Catalina (10.15). We will send email to the mailing list if and when ADFR software suite or an alternative will be available for this version of macOS. If you already are using Catalina, we recommend install VirtualBox and running ADFR software suite inside the virtual box.
-
-The ADFR software suite was developed in the Sanner lab at the `Center for Computational Structural Biology (CCSB) <https://ccsb.scripps.edu>`_ formerly known as the Molecular Graphics Laboratory (MGL) of The Scripps Research Institute for visualization and analysis of molecular structures. You can find more information about the ADFR software suite installation process here: `https://ccsb.scripps.edu/adfr/downloads <https://ccsb.scripps.edu/adfr/downloads/>`_. The current version contains the following tools for docking:
-
-    - ADFR v1.2 and associate scripts
-    - AGFR v1.2
-    - AutoSite v1.0 and v1.1
-    - ADCP v1.0
-    - AutoGrid4.2
-    - prepare_ligand
-    - prepare_receptor
-
-Moreover, the ADFR software suite provides a number of software tools for automated docking and peripheral tasks. These tools are implemented using the Python, C++ and C programming languages and a re-usable component philosophy. To avoid Python packages mismatches we opted to shift ADFR suite with a self-contain Python interpreter that is isolated from the default Python interpreter installed on your computer (except for Windows installations). Details about the implementation and packages provided by the ADFR software suite can be found here: `https://ccsb.scripps.edu/adfr/implementation <https://ccsb.scripps.edu/adfr/implementation/>`_
-
-**Citations**:
-
-    - Zhang, Y., Forli, S., Omelchenko, A., & Sanner, M. F. (2019). AutoGridFR: Improvements on AutoDock Affinity Maps and Associated Software Tools. Journal of Computational Chemistry, 40(32), 2882-2886.
-    - Zhang, Y., & Sanner, M. F. (2019). AutoDock CrankPep: combining folding and docking to predict protein–peptide complexes. Bioinformatics, 35(24), 5121-5127.
-    - Ravindranath, P. A., & Sanner, M. F. (2016). AutoSite: an automated approach for pseudo-ligands prediction—from ligand-binding sites identification to predicting key ligand atoms. Bioinformatics, 32(20), 3142-3149.
-    - Ravindranath, P. A., Forli, S., Goodsell, D. S., Olson, A. J., & Sanner, M. F. (2015). AutoDockFR: advances in protein-ligand docking with explicitly specified binding site flexibility. PLoS computational biology, 11(12), e1004586.
-    - Zhao, Y., Stoffler, D., & Sanner, M. (2006). Hierarchical and multi-resolution representation of protein flexibility. Bioinformatics, 22(22), 2768-2774.
-
-Meeko
+Python package Meeko
 -----
 
-The Python package ``meeko`` is a new type of package developped in the Forli lab also at the `Center for Computational Structural Biology (CCSB) <https://ccsb.scripps.edu>`_.  It provides tools covering other docking aspects not handled by the ADFR software suite. This package provides addtionnal tools for the following docking protocols:
+The Python package ``meeko`` is package recently developped in the Forli lab also at the `Center for Computational Structural Biology (CCSB) <https://ccsb.scripps.edu>`_. As showcased in the Colab examples, `Meeko <https://github.com/forlilab/Meeko>`_ provides commandline scripts for ligand preparation, receptor preparation and other essential tools for the following docking protocols:
 
+    - Docking with flexible macrocycles
+    - Flexible docking
+    - Covalent docking
+    - Reactive docking
     - Hydrated docking
-    - Macrocycles
 
 **Meeko installation using pip**:
 
 .. note::
 
-    When using ``pip``, it's good pratice to use a virtual environment and also the easiest solution. An example with the `Conda package manager <https://docs.conda.io/en/latest/>`_ is available further down.
-
-.. warning::
-
-    OpenBabel executable and library must be installed first, see `installation instruction <https://open-babel.readthedocs.io/en/latest/Installation/install.html#install-binaries>`_.
+    When using ``pip``, it's good practice to do so in a virtual (conda, mamba, etc.) environment instead of the base environment. An example with the `Conda package manager <https://docs.conda.io/en/latest/>`_ is available further down.
 
 .. code-block:: bash
     
@@ -57,6 +29,8 @@ The Python package ``meeko`` is a new type of package developped in the Forli la
 If the installation was successful, you should now be able to access to the following command from your terminal by typing:
 
     - mk_prepare_ligand.py
+    - mk_prepare_receptor.py
+    - mk_export.py
 
 **Meeko installation in a Conda environment**:
 
@@ -69,6 +43,35 @@ Type the following command to install ``NumPy``, ``OpenBabel`` and ``meeko``:
 .. code-block:: bash
     
     $ conda activate vina
-    $ conda install python=3.9.7    # not strictly needed but prevents RDKit incompatibility
+    $ conda install python=3.10    # for ProDy interoperability
     $ conda install -c conda-forge numpy openbabel scipy rdkit
     $ pip install meeko
+
+
+ADFR software suite
+-------------------
+
+.. warning::
+
+    macOS users please note that ADFR software suite is NOT working under Catalina (10.15). We will send email to the mailing list if and when ADFR software suite or an alternative will be available for this version of macOS. If you already are using Catalina, we recommend install VirtualBox and running ADFR software suite inside the virtual box. 
+
+The ADFR software suite was developed in the Sanner lab at the `Center for Computational Structural Biology (CCSB) <https://ccsb.scripps.edu>`_ formerly known as the Molecular Graphics Laboratory (MGL) of The Scripps Research Institute for visualization and analysis of molecular structures. You can find more information about the ADFR software suite installation process here: `https://ccsb.scripps.edu/adfr/downloads <https://ccsb.scripps.edu/adfr/downloads/>`_. The current version contains the following tools for docking:
+
+    - ADFR v1.2 and associate scripts
+    - AGFR v1.2
+    - AutoSite v1.0 and v1.1
+    - ADCP v1.0
+    - AutoGrid4.2
+    - prepare_ligand
+    - prepare_receptor
+
+Moreover, the ADFR software suite provides a number of software tools for automated docking and peripheral tasks. These tools are implemented using the Python, C++ and C programming languages and a re-usable component philosophy. To avoid Python packages mismatches we opted to shift ADFR suite with a self-contain Python interpreter that is isolated from the default Python interpreter installed on your computer (except for Windows installations). Details about the implementation and packages provided by the ADFR software suite can be found here: `https://ccsb.scripps.edu/adfr/implementation <https://ccsb.scripps.edu/adfr/implementation/>`_
+
+**Citations**:
+
+    - Zhang, Y., Forli, S., Omelchenko, A., & Sanner, M. F. (2019). AutoGridFR: Improvements on AutoDock Affinity Maps and Associated Software Tools. Journal of Computational Chemistry, 40(32), 2882-2886.
+    - Zhang, Y., & Sanner, M. F. (2019). AutoDock CrankPep: combining folding and docking to predict protein–peptide complexes. Bioinformatics, 35(24), 5121-5127.
+    - Ravindranath, P. A., & Sanner, M. F. (2016). AutoSite: an automated approach for pseudo-ligands prediction—from ligand-binding sites identification to predicting key ligand atoms. Bioinformatics, 32(20), 3142-3149.
+    - Ravindranath, P. A., Forli, S., Goodsell, D. S., Olson, A. J., & Sanner, M. F. (2015). AutoDockFR: advances in protein-ligand docking with explicitly specified binding site flexibility. PLoS computational biology, 11(12), e1004586.
+    - Zhao, Y., Stoffler, D., & Sanner, M. (2006). Hierarchical and multi-resolution representation of protein flexibility. Bioinformatics, 22(22), 2768-2774.
+

docs/source/index.rst

@@ -9,13 +9,13 @@ Availability
 ------------
 AutoDock Vina can be easily installed with all its dependencies using `pip` or `conda` package managers.
 
-All **source code** is available under the `Apache License, version 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`_ from `github.com/ccsb-scripps/AutoDock-Vina <https://github.com/ccsb-scripps/AutoDock-Vina>`_ and the Python Package index `pypi.org/project/Vina <pypi.org/project/Vina>`_.
+All **source code** is available under the `Apache License, version 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`_ from `github.com/ccsb-scripps/AutoDock-Vina <https://github.com/ccsb-scripps/AutoDock-Vina>`_ and the Python Package index `pypi.org/project/Vina <https://pypi.org/project/Vina>`_.
 
 Participating
 -------------
 Please report bugs or enhancement requests through the `Issue Tracker <https://github.com/ccsb-scripps/AutoDock-Vina/issues>`_.
 
-AutoDock Vina is **open source** and welcomes your contributions. `Fork the repository on GitHub <https://github.com/ccsb-scripps/AutoDock-Vina>`_ and submit a pull request. Participate on the `developer mailing list <http://mgldev.scripps.edu/mailman/listinfo/autodock>`_.
+AutoDock Vina is **open source** and welcomes your contributions. `Fork the repository on GitHub <https://github.com/ccsb-scripps/AutoDock-Vina>`_ and submit a pull request. 
 
 .. toctree::
    :maxdepth: 2
@@ -24,6 +24,7 @@ AutoDock Vina is **open source** and welcomes your contributions. `Fork the repo
 
    introduction
    installation
+   colab_examples
    faq
    citations
    changes

docs/source/installation.rst

@@ -7,37 +7,21 @@ Installation
 
     Currently, the python bindings and the binary installation are two separate processes. The installation of the python bindings does not include the Vina executable, and vice versa.
 
-Unix- and Linux-based OS
+Pre-compiled Executables: vina and vina_split
 ------------------------
 
-Vina is expected to work on x86 and compatible 64-bit Linux systems. The executable for the latest release are available here: `https://github.com/ccsb-scripps/AutoDock-Vina/releases <https://github.com/ccsb-scripps/AutoDock-Vina/releases>`_.
+The executables for the latest release are available here: `https://github.com/ccsb-scripps/AutoDock-Vina/releases <https://github.com/ccsb-scripps/AutoDock-Vina/releases>`_.
 
 **Running**:
 
 .. code-block:: bash
 
-    ./vina_1.2.0_linux_x86_64 --help
+    ./vina_<version number>_<OS name>_<architecture> --help
 
-If the executable is in your PATH, you can just type "vina --help" instead.
 
-macOS
-------
-
-Vina is expected to work on macOS 10.15 (Catalina) and newer. The executable for the latest release are available here: `https://github.com/ccsb-scripps/AutoDock-Vina/releases <https://github.com/ccsb-scripps/AutoDock-Vina/releases>`_.
-
-**Running**:
-
-.. code-block:: bash
-
-    ./vina_1.2.0_macos_x86_64 --help
-
-If the executable is in your PATH, you can just type "vina --help" instead.
-
-Python bindings
+Python bindings (Linux and Mac only)
 ---------------
 
-Currently working on Linux and Mac. We did not test on Windows.
-
 **AutoDock Vina installation using pip**:
 
 .. note::

readthedocs.yml

@@ -15,14 +15,15 @@ sphinx:
 formats: all
 
 build:
-  image: latest
+  os: ubuntu-22.04
+  tools:
+    python: "miniconda3-4.7"
 
 conda:
   environment: build/python/environment.yml
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-   version: 3
    install:
    - method: setuptools
      path: build/python