Fix docs (#805)

* fix formatting * fix list numbering * try again to fix hyperlink and numbered list * try again * another attempt * try agian * update docs env yml * try again * fix typo * add missing line * add symengine to docs env * add symengine channel * add pip to docs env * fix typo * remove subtopology from docs * exclude pydantic related attribute from docs generation * try to fix autosummary * try to get rid of __base_doc__ in favor of traditional docstring * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * update conf.py and docs env * fix rst formatting * revert change on base_doc on atom * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix some idnetns pro * remove __base_doc__ from all * remove auto_doc * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * remove commented out block * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * split summary table in data structures * Update docs/index.rst Co-authored-by: CalCraven <[email protected]> --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: CalCraven <[email protected]>
mosdef-hub · Mar 17, 2024 · 8e80c99 · 8e80c99
1 parent d3fca73
commit 8e80c99
Show file tree

Hide file tree

Showing 23 changed files with 143 additions and 463 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -19,8 +19,8 @@
 # -- Project information -----------------------------------------------------
 
 project = "gmso"
-copyright = "2020, mosdef-hub, Vanderbilt University"
-author = "Matt Thompson, Alex Yang, Ray Matsumoto, Parashara Shamaprasad, Umesh Timalsina, Co Quach, Ryan S. DeFever, Justin Gilmer"
+copyright = "2024, mosdef-hub, Vanderbilt University"
+author = "Matt Thompson, Alex Yang, Ray Matsumoto, Parashara Shamaprasad, Umesh Timalsina, Co D. Quach, Ryan S. DeFever, Justin Gilmer"
 
 # The full version, including alpha/beta/rc tags
 version = "0.12.0"
@@ -49,7 +49,7 @@
 napoleon_use_param = False
 napoleon_use_ivar = True
 
-intersphinx_mapping = {"python": ("https://docs.python.org/3.7", None)}
+intersphinx_mapping = {"python": ("https://docs.python.org/3.11", None)}
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -69,9 +69,9 @@
 # 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_static_path = ["_static"]
 
-_python_doc_base = "http://docs.python.org/3.7"
+_python_doc_base = "http://docs.python.org/3.11"
 
 source_suffix = ".rst"
 

diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -18,7 +18,7 @@ Version control
 ---------------
 
 We currently use the "standard" Pull Request model. Contributions should be implemented on feature branches of forks.
-Please try to keep the `master` branch of your fork up-to-date with the `master` branch of the main repository.
+Please try to keep the `main` branch of your fork up-to-date with the `main` branch of the main repository.
 
 Propose a single set of related changes
 ****************************************

diff --git a/docs/data_structures.rst b/docs/data_structures.rst
@@ -8,92 +8,99 @@ Core Classes
     :nosignatures:
 
     gmso.Topology
-    gmso.SubTopology
     gmso.Atom
     gmso.Bond
     gmso.Angle
     gmso.Dihedral
     gmso.Improper
-    gmso.AtomType
-    gmso.BondType
-    gmso.AngleType
-    gmso.DihedralType
-    gmso.ImproperType
 
 
 Topology
 ********
     .. autoclass:: gmso.Topology
         :members: add_site, add_connection, update_topology
 
-SubTopology
-***********
-    .. autoclass:: gmso.SubTopology
-        :members:
-
 Atom
 ****
     .. autoclass:: gmso.Atom
         :members:
+        :exclude-members: model_config, model_fields
 
 Bond
 ****
     .. autoclass:: gmso.Bond
         :members:
+        :exclude-members: model_config, model_fields
 
 Angle
 *****
     .. autoclass:: gmso.Angle
         :members:
+        :exclude-members: model_config, model_fields
 
 Dihedral
 ********
     .. autoclass:: gmso.Dihedral
         :members:
+        :exclude-members: model_config, model_fields
 
 Improper
 ********
     .. autoclass:: gmso.Improper
         :members:
+        :exclude-members: model_config, model_fields
 
 
 Potential Classes
 =================
+.. autosummary::
+    :nosignatures:
+
+    gmso.AtomType
+    gmso.BondType
+    gmso.AngleType
+    gmso.DihedralType
+    gmso.ImproperType
+    gmso.PairPotentialType
 
 AtomType
 ********
     .. autoclass:: gmso.AtomType
         :members:
+        :exclude-members: model_config, model_fields
 
 BondType
 ********
     .. autoclass:: gmso.BondType
         :members:
+        :exclude-members: model_config, model_fields
 
 AngleType
 **********
     .. autoclass:: gmso.AngleType
         :members:
+        :exclude-members: model_config, model_fields
 
 DihedralType
 ************
     .. autoclass:: gmso.DihedralType
         :members:
+        :exclude-members: model_config, model_fields
 
 ImproperType
 ************
     .. autoclass:: gmso.ImproperType
         :members:
+        :exclude-members: model_config, model_fields
 
 PairPotentialType
-************
+*****************
     .. autoclass:: gmso.PairPotentialType
         :members:
+        :exclude-members: model_config, model_fields
 
 ForceField
 ==========
     .. autoclass:: gmso.ForceField
         :members:
-
-
-=======
+        :exclude-members: model_config, model_fields
diff --git a/docs/docker.rst b/docs/docker.rst
@@ -35,13 +35,11 @@ Alternatively, you can also start a Bourne shell to use python from the containe
     container's lifecycle.  If the container is removed, any changes or code additions will not persist.  See the section below for
     persistent data.
 
-.. Note::
-
-Note
+.. note::
 
-The -it flags connect your keyboard to the terminal running in the container.
-You may run the prior command without those flags, but be aware that the container will not respond to any keyboard input.
-In that case, you would need to use the docker ``ps`` and ``docker kill`` commands to shut down the container.
+    The -it flags connect your keyboard to the terminal running in the container.
+    You may run the prior command without those flags, but be aware that the container will not respond to any keyboard input.
+    In that case, you would need to use the docker ``ps`` and ``docker kill`` commands to shut down the container.
 
 
 Persisting User Volumes

diff --git a/docs/docs-env.yml b/docs/docs-env.yml
@@ -1,17 +1,24 @@
 name: gmso-docs
 channels:
   - conda-forge
+  - symengine
 dependencies:
-  - python>=3.8
+  - python=3.11
+  - numpy
+  - sympy
+  - symengine
+  - python-symengine
+  - unyt >= 2.4
+  - boltons
+  - lxml
+  - pydantic >= 2
+  - networkx
+  - ele >= 0.2.0
+  - mbuild
+  - foyer
+  - forcefield-utilities
+  - pip
   - pip:
-    - numpy
-    - sympy
-    - unyt >= 2.4
-    - boltons
-    - lxml
-    - pydantic < 1.9.0
-    - networkx
-    - ele >= 0.2.0
     - numpydoc
     - sphinx
     - sphinx_rtd_theme

diff --git a/docs/index.rst b/docs/index.rst
@@ -5,18 +5,22 @@
 
 GMSO: Flexible storage of chemical topology for molecular simulation
 ====================================================================
-`GMSO`is a flexible storage of chemical topology for molecular simulation.
-With a few lines of `GMSO` code, together with [`mBuild`](https://mbuild.mosdef.org) and [`foyer`](https://foyer.mosdef.org), users can rapidly prototype arbitrary parameterized chemical systems and generate data files for a wide variety of simulation engines.
+
+.. image:: https://img.shields.io/badge/license-MIT-blue.svg
+    :target: http://opensource.org/licenses/MIT
+
+`GMSO` is a flexible storage of chemical topology for molecular simulation.
+With a few lines of `GMSO` code, together with `mBuild <https://mbuild.mosdef.org>`_ and `foyer <https://foyer.mosdef.org>`_, users can rapidly prototype arbitrary parameterized chemical systems and generate data files for a wide variety of simulation engines.
 
 
 GMSO is a part of the MoSDeF ecosystem
 -----------------------------------------
 `GMSO` is designed to be a general and flexible representation of chemical topolgies for molecular simulation.
 With an emphasis on assuming as little as possible about the chemical system, model, or engine, `GMSO` can enable support for a variety of systems.
-`GMSO` is a part of the [MoSDeF (Molecular Simulation and Design Framework)](https://mosdef.org) ecosystem, and is intended to be the backend replacement for the [`foyer` package](https://foyer.mosdef.org).
+`GMSO` is a part of the `MoSDeF (Molecular Simulation and Design Framework) <https://mosdef.org>`_ ecosystem, and is intended to be a generalized alternative for the `foyer package <https://foyer.mosdef.org>`_.
 Libraries in the MoSDeF ecosystem are designed to provide utilities neccessary to streamline
 a researcher's simulation workflow. When setting up simulation studies,
-we also recommend users to follow the [TRUE](https://www.tandfonline.com/doi/full/10.1080/00268976.2020.1742938)
+we also recommend users to follow the `TRUE <https://www.tandfonline.com/doi/full/10.1080/00268976.2020.1742938>`_
 (Transparent, Reproducible, Usable-by-others, and Extensible) standard, which is a set of common
 practices meant to improve the reproducibility of computational simulation research.
 
@@ -27,52 +31,47 @@ Goals and Features
 `GMSO`'s goal is to provide a flexible backend framework to store topological information of a chemical system in a reproducible fashion.
 **Topology** in this case is defined as the information needed to initialize a molecular simulation.
 Depending on the type of simulation performed, this ranges from:
+
 * particle positions
 * particle connectivity
 * box information
 * forcefield data
-    - functional forms defined as [`sympy` expressions](https://www.sympy.org)
-    - parameters with defined units
-    - partial charges
-    - tabulated data
-    - etc.
+
+    * functional forms defined as `sympy <https://www.sympy.org>`_ expressions
+    * parameters with defined units
+    * partial charges
+    * tabulated data
+    * etc.
+
 * Other optional data
-    - particle mass
-    - elemental data
-    - etc.
+
+    * particle mass
+    * elemental data
+    * etc.
 
 With these driving goals for `GMSO`, the following features are enabled:
-1. __Supporting a variety of models__ in the molecular simulation/computational
-  chemistry community_:
-  No assumptions are made about an interaction site
-  representing an atom or bead, instead these can be atomistic,
-  united-atom/coarse-grained, polarizable, and other models!
-
-1. __Greater flexibility for exotic potentials__: The [`AtomType`](./gmso/core/atom_type.py) (and [analogue
-  classes for intramolecular interactions](./gmso/core)) uses [`sympy`](https://www.sympy.org) to store any
-  potential that can be represented by a mathematical expression.
-
-1. __Adaptable for new engines__: by not being designed for
-  compatibility with any particular molecular simulation engine or ecosystem,
-  it becomes more tractable for developers in the community to add glue for
-  engines that are not currently supported.
-
-1. __Compatibility with existing community tools__: No single molecular simulation
-  tool will ever be a silver bullet, so ``GMSO`` includes functions to convert
-  between various file formats and libraries. These can be used in their own right to convert between objects in-memory
-  and also to support conversion to file formats not natively supported at
-  any given time. Currently supported conversions include:
-    * [`ParmEd`](./gmso/external/convert_parmed.py)
-    * [`OpenMM`](./gmso/external/convert_openmm.py)
-    * [`mBuild`](./gmso/external/convert_mbuild.py)
-    * more in the future!
-
-1. __Native support for reading and writing many common file formats__: We natively have support for:
-    * [`XYZ`](./gmso/formats/xyz.py)
-    * [`GRO`](./gmso/formats/gro.py)
-    * [`TOP`](gmso/formats/top.py)
-    * [`LAMMPSDATA`](gmso/formats/lammpsdata.py)
-    * indirect support, through other libraries, for many more!
+
+    #.  **Supporting a variety of models**: in the molecular simulation/computational chemistry community: No assumptions are made about an interaction site representing an atom or bead, instead these can be atomistic, united-atom/coarse-grained, polarizable, and other models!
+
+    #.  **Greater flexibility for exotic potentials**: The `AtomType` (and analogue classes for intramolecular interactions) uses `sympy <https://www.sympy.org>`_ to store any potential that can be represented by a mathematical expression.
+
+    #.  **Adaptable for new engines**: by not being designed for compatibility with any particular molecular simulation engine or ecosystem, it becomes more tractable for developers in the community to add glue for engines that are not currently supported.
+
+    #.  **Compatibility with existing community tools**: No single molecular simulation tool will ever be a silver bullet, so ``GMSO`` includes functions to convert between various file formats and libraries. These can be used in their own right to convert between objects in-memory and also to support conversion to file formats not natively supported at any given time. Currently supported conversions include:
+
+        * `ParmEd`
+        * `OpenMM`
+        * `mBuild`
+        * more in the future!
+
+    #.  **Native support for reading and writing many common file formats**:
+
+        * `XYZ`
+        * `GRO`
+        * `TOP`
+        * `LAMMPSDATA`
+        * `GSD`
+        * indirect support, through other libraries, for many more!
 
 
 .. toctree::

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -50,8 +50,8 @@ Once all dependencies have been installed and the ``conda`` environment has been
 Supported Python Versions
 -------------------------
 
-Python 3.8-3.11 is the recommend version for users. It is the only version on which
-development and testing consistently takes place.  Older (3.6-3.7) and newer (3.12+)
+Python 3.9-3.11 is the recommend version for users. It is the only version on which
+development and testing consistently takes place.  Older (3.6-3.9) and newer (3.12+)
 versions of Python 3 are likely to work but no guarantee is made and, in
 addition, some dependencies may not be available for other versions.  No effort
 is made to support Python 2 because it is considered obsolete as of early 2020.