Merge pull request #61 from xiaoruiDong/docs

Huge Improvement of Documentation
xiaoruiDong · Sep 11, 2023 · 8f16e96 · 8f16e96
2 parents 9f6f3de + 2a0e19f
commit 8f16e96
Show file tree

Hide file tree

Showing 75 changed files with 2,053 additions and 710 deletions.
diff --git a/docs/source/_static/GitHub_icon.svg b/docs/source/_static/GitHub_icon.svg
diff --git a/docs/source/_static/Google_Scholar_icon.svg b/docs/source/_static/Google_Scholar_icon.svg
diff --git a/docs/source/_static/LinkedIn_icon.svg b/docs/source/_static/LinkedIn_icon.svg
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
@@ -0,0 +1,4 @@
+.social-icon {
+    height: 1rem;
+    width: auto;
+}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -10,16 +10,17 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import datetime
 import os
 import sys
 sys.path.insert(0, os.path.abspath('../../'))
-import sphinx_rtd_theme
 
 # -- Project information -----------------------------------------------------
 
 project = 'RDMC'
-copyright = '2020, Xiaorui Dong'
-author = 'Xiaorui Dong'
+copyright = f'2020-{datetime.datetime.now().year}, Xiaorui Dong'
+author = 'Xiaorui Dong, Lagnajit Pattanaik, Shih-Cheng Li, ' \
+         'Kevin Spiekermann, Hao-Wei Pang, and William H. Green'
 
 # The full version, including alpha/beta/rc tags
 release = '0.1'
@@ -50,14 +51,29 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
-html_theme = 'sphinx_rtd_theme'
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+html_theme = 'pydata_sphinx_theme'
+html_theme_options = {
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/xiaoruidong/rdmc",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+        },
+    ]
+}
+
+# Make the `Returns` in docstring behave like `Args`
+napoleon_custom_sections = [('Returns', 'params_style')]
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+html_css_files = [
+    'custom.css',
+]
 
 # -- Packages that are not importable from the default environment ---------
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,29 +1,114 @@
 RDMC Documentation
 ===================
 
-**RDMC (RDkit Molecule and Conformer)** is A light-weight wrapper for **RDKit** Molecule and Conformer related operations. RDkit is great! I like its versatility and speed, but
-personally, I find learning to use RDKit is not easy. I usually have to go back and forth to check if RDKit has certain methods and how to use them,
-since those molecule operations are usually located in different modules. I wrote this tiny thing majorly aiming to make my life easier and to
-provide a convenient tool so that users can just import a single module / class instead of remembering which method in what module.
+**RDMC (Reaction Data and Molecular Conformer)** is an open-source lightweight software package specialized in handling Reaction Data and Molecular (including transition states) Conformers.
 
-To start with, simply try::
+It contains various modules and classes (e.g., ``RDKitMol``, ``Reaction``, ``view``) helpful for relevant tasks to make conversion, visualization, manipulation, and analysis of molecules easier.
+It also provides solutions to pipelining tasks to achieve high-throughput generating and processing of large amount of molecule/reaction data. It is written in Python and has dependencies only
+on popular packages (i.e., ``numpy``, ``scipy``, ``matplotlib``, ``rdkit``, ``openbabel``, ``py3dmol``, ``ase``, ``networkx``, ``cclib``), and you can easily incorporate it into your own Python scripts.
 
-    from rdmc.mol import RDKitMol
+The source code of the RDMC software package is hosted on GitHub, and its binary distribution is available on Anaconda Cloud. The easiest way to install RDMC is to use ``conda`` or ``mamba``::
 
-and see what you can do with this ``RDKitMol`` class!
+    conda install -c xiaoruidong rdmc
 
+Or
+
+.. code-block:: bash
+
+    mamba install -c xiaoruidong rdmc
+
+``conda`` can be installed by via `Anaconda <https://www.anaconda.com/download/>`_ and, ``mamba`` can be installed via `Mambaforge <https://github.com/conda-forge/miniforge#mambaforge>`_.
+
+You can also install RDMC from the source code:
+
+.. code-block:: bash
+
+    git clone https://github.com/xiaoruidong/rdmc
+    cd RDMC
+    conda env create -f environment.yml
+    conda activate rdmc
+    python -m pip install --no-deps -vv ./
+
+To start with, simply try:
+
+.. code-block:: python
+
+    from rdmc import RDKitMol, Reaction
+    mol = RDKitMol('CCO')
+    rxn = Reaction('CCO>>CC(=O)O')
+
+And see what the ``mol`` and ``rxn`` are capable of! The full lists of APIs of :obj:`RDKitMol <rdmc.mol.RDKitMol>` and :obj:`Reaction <rdmc.reaction.Reaction>` are provided in this documentation.
+
+We also provided a few notebooks (available in ``\ipython`` and `Colab <https://drive.google.com/drive/folders/1bHSChJOocycE5ZfbnGkocX4-OFVDhShW?usp=sharing>`_) to demonstrate the usage of RDMC. Please feel invited to try them out!
+
+RDMC is developed by
+
+- Xiaorui Dong (|github_xiaorui|_ \| |linkedin_xiaorui|_ \| |gs_xiaorui|_),
+- Dr. Lagnajit Pattanaik (|github_lucky|_ \| |linkedin_lucky|_ \| |gs_lucky|_),
+- Dr. Shih-Cheng Li (|github_shihcheng|_ \| |linkedin_shihcheng|_ \| |gs_shihcheng|_),
+- Dr. Kevin Spiekermann (|github_kevin|_ \| |linkedin_kevin|_ \| |gs_kevin|_),
+- Hao-Wei Pang (|github_haowei|_ \| |linkedin_haowei|_ \| |gs_haowei|_),
+- Prof. William H. Green (|linkedin_bill|_ \| |gs_bill|_)
+
+at `Green Research Group <https://greengroup.mit.edu>`_ at `Massachusetts Institute of Technology (MIT) <https://www.mit.edu>`_.
+For any questions while using RDMC, please contact us via the `GitHub issue page <https://github.com/xiaoruiDong/RDMC/issues>`_ or email us at `[email protected] <mailto:[email protected]>`_.
 
 Contents
 ========
 .. toctree::
    :maxdepth: 2
 
-   rdmc
-   license
+   reference/rdmc
+   reference/credits
+   reference/cite
+   reference/license
 
 
-Indices and tables
+APIs
 ===================
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
+
+
+.. |github| image:: _static/GitHub_icon.svg
+    :class: social-icon
+.. |github_xiaorui| replace:: |github|
+.. _github_xiaorui: https://github.com/xiaoruiDong
+.. |github_lucky| replace:: |github|
+.. _github_lucky: https://github.com/PattanaikL
+.. |github_shihcheng| replace:: |github|
+.. _github_shihcheng: https://github.com/shihchengli
+.. |github_kevin| replace:: |github|
+.. _github_kevin: https://github.com/kspieks
+.. |github_haowei| replace:: |github|
+.. _github_haowei: https://github.com/hwpang
+
+.. |linkedin| image:: _static/LinkedIn_icon.svg
+    :class: social-icon
+.. |linkedin_xiaorui| replace:: |linkedin|
+.. _linkedin_xiaorui: https://www.linkedin.com/in/xiaorui-dong/
+.. |linkedin_lucky| replace:: |linkedin|
+.. _linkedin_lucky: https://www.linkedin.com/in/lagnajit-pattanaik-94a564108/
+.. |linkedin_shihcheng| replace:: |linkedin|
+.. _linkedin_shihcheng: https://www.linkedin.com/in/shih-cheng-li-564006207/
+.. |linkedin_kevin| replace:: |linkedin|
+.. _linkedin_kevin: https://www.linkedin.com/in/kspiekermann/
+.. |linkedin_haowei| replace:: |linkedin|
+.. _linkedin_haowei: https://www.linkedin.com/in/hao-wei-pang/
+.. |linkedin_bill| replace:: |linkedin|
+.. _linkedin_bill: https://www.linkedin.com/in/william-green-63a9a218/
+
+.. |google_scholar| image:: _static/Google_Scholar_icon.svg
+    :class: social-icon
+.. |gs_xiaorui| replace:: |google_scholar|
+.. _gs_xiaorui: https://scholar.google.com/citations?hl=en&user=r5Wz41EAAAAJ
+.. |gs_lucky| replace:: |google_scholar|
+.. _gs_lucky: https://scholar.google.com/citations?hl=en&user=bVT6lpwAAAAJ
+.. |gs_shihcheng| replace:: |google_scholar|
+.. _gs_shihcheng: https://scholar.google.com/citations?hl=en&user=kc_rvjoAAAAJ
+.. |gs_kevin| replace:: |google_scholar|
+.. _gs_kevin: https://scholar.google.com/citations?hl=en&user=qg2LmbgAAAAJ
+.. |gs_haowei| replace:: |google_scholar|
+.. _gs_haowei: https://scholar.google.com/citations?hl=en&user=hmkEmtcAAAAJ
+.. |gs_bill| replace:: |google_scholar|
+.. _gs_bill: https://scholar.google.com/citations?hl=en&user=PGQTLWwAAAAJ
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
diff --git a/docs/source/rdmc.external.xyz2mol.rst b/docs/source/rdmc.external.xyz2mol.rst
diff --git a/docs/source/reference/cite.rst b/docs/source/reference/cite.rst
@@ -0,0 +1,21 @@
+How to cite RDMC
+================
+
+Text form
+
+.. code-block:: tex
+
+    Dong, X., Pattanaik, L., Li, S.-C., Spiekermann, K., Pang, H.-W., Green, William H (2023). RDMC: Reaction Data and Molecular Conformer (Version 0.1.0) [Computer software]. https://github.com/xiaoruiDong/RDMC
+
+
+BibTeX form
+
+.. code-block:: tex
+
+    @misc{RDMC,
+        author = {Dong, Xiaorui and Pattanaik, Lagnajit and Li, Shih-Cheng and Spiekermann, Kevin and Pang, Hao-Wei and Green, William H.},
+        title = {RDMC: Reaction Data and Molecular Conformer Software Package, version 0.1.0},
+        year = {2023},
+        publisher = {GitHub},
+        howpublished = {\url{https://github.com/xiaoruiDong/RDMC}}}
+
diff --git a/docs/source/rdmc.conf.rst → docs/source/reference/conf.rst b/docs/source/rdmc.conf.rst → docs/source/reference/conf.rst
diff --git a/docs/source/reference/conformer_generation/embedding_geometries/align.rst b/docs/source/reference/conformer_generation/embedding_geometries/align.rst
@@ -0,0 +1,7 @@
+rdmc.conformer_generation.align
+=================================
+
+.. automodule:: rdmc.conformer_generation.align
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/conformer_generation/embedding_geometries/embedders.rst b/docs/source/reference/conformer_generation/embedding_geometries/embedders.rst
@@ -0,0 +1,7 @@
+rdmc.conformer_generation.embedders
+===================================
+
+.. automodule:: rdmc.conformer_generation.embedders
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/conformer_generation/embedding_geometries/index.rst b/docs/source/reference/conformer_generation/embedding_geometries/index.rst
@@ -0,0 +1,9 @@
+Embedding Geometries
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+   embedders
+   align
+   ts_guessers
diff --git a/docs/source/reference/conformer_generation/embedding_geometries/ts_guessers.rst b/docs/source/reference/conformer_generation/embedding_geometries/ts_guessers.rst
@@ -0,0 +1,7 @@
+rdmc.conformer_generation.ts_guessers
+======================================
+
+.. automodule:: rdmc.conformer_generation.ts_guessers
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/conformer_generation/geometry_optimization/index.rst b/docs/source/reference/conformer_generation/geometry_optimization/index.rst
@@ -0,0 +1,8 @@
+Geometry Optimization
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+   optimizers
+   ts_optimizers
diff --git a/docs/source/reference/conformer_generation/geometry_optimization/optimizers.rst b/docs/source/reference/conformer_generation/geometry_optimization/optimizers.rst
@@ -0,0 +1,7 @@
+rdmc.conformer_generation.optimizers
+=====================================
+
+.. automodule:: rdmc.conformer_generation.optimizers
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/conformer_generation/geometry_optimization/ts_optimizers.rst b/docs/source/reference/conformer_generation/geometry_optimization/ts_optimizers.rst
@@ -0,0 +1,7 @@
+rdmc.conformer_generation.ts_optimizers
+=======================================
+
+.. automodule:: rdmc.conformer_generation.ts_optimizers
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/conformer_generation/index.rst b/docs/source/reference/conformer_generation/index.rst
@@ -0,0 +1,16 @@
+rdmc.conformer_generation
+==========================
+
+.. automodule:: rdmc.conformer_generation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. toctree::
+   :maxdepth: 2
+
+   embedding_geometries/index
+   geometry_optimization/index
+   postprocessing/index
+   workflow/index
+   utils
diff --git a/docs/source/reference/conformer_generation/postprocessing/index.rst b/docs/source/reference/conformer_generation/postprocessing/index.rst
@@ -0,0 +1,10 @@
+Postprocessing
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+   verifiers
+   ts_verifiers
+   pruners
+   solvation
diff --git a/docs/source/reference/conformer_generation/postprocessing/pruners.rst b/docs/source/reference/conformer_generation/postprocessing/pruners.rst
@@ -0,0 +1,7 @@
+rdmc.conformer_generation.pruners
+=======================================
+
+.. automodule:: rdmc.conformer_generation.pruners
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/conformer_generation/postprocessing/solvation.rst b/docs/source/reference/conformer_generation/postprocessing/solvation.rst
@@ -0,0 +1,7 @@
+rdmc.conformer_generation.solvation
+=======================================
+
+.. automodule:: rdmc.conformer_generation.solvation
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/conformer_generation/postprocessing/ts_verifiers.rst b/docs/source/reference/conformer_generation/postprocessing/ts_verifiers.rst
@@ -0,0 +1,7 @@
+rdmc.conformer_generation.ts_verifiers
+=======================================
+
+.. automodule:: rdmc.conformer_generation.ts_verifiers
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/conformer_generation/postprocessing/verifiers.rst b/docs/source/reference/conformer_generation/postprocessing/verifiers.rst
@@ -0,0 +1,7 @@
+rdmc.conformer_generation.verifiers
+=======================================
+
+.. automodule:: rdmc.conformer_generation.verifiers
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/conformer_generation/utils.rst b/docs/source/reference/conformer_generation/utils.rst
@@ -0,0 +1,7 @@
+Utils
+=====================================
+
+.. automodule:: rdmc.conformer_generation.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/conformer_generation/workflow/generators.rst b/docs/source/reference/conformer_generation/workflow/generators.rst
@@ -0,0 +1,7 @@
+rdmc.conformer_generation.generators
+=====================================
+
+.. automodule:: rdmc.conformer_generation.generators
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/conformer_generation/workflow/index.rst b/docs/source/reference/conformer_generation/workflow/index.rst
@@ -0,0 +1,10 @@
+Workflow
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+   generators
+   ts_generators
+   metrics
+   sampler