Writing documentation for the OpenBabel Converter

README.md

@@ -7,23 +7,23 @@ mda-openbabel-converter
 | **Status**         | [![GH Actions Status][badge_actions]][url_actions] [![codecov][badge_codecov]][url_codecov] |
 | **Community**      | [![License: GPL v2][badge_license]][url_license]  [![Powered by MDAnalysis][badge_mda]][url_mda]|
 
-[badge_actions]: https://github.com/lunamorrow/mda_openbabel_converter/actions/workflows/gh-ci.yaml/badge.svg
-[badge_codecov]: https://codecov.io/gh/lunamorrow/mda_openbabel_converter/branch/main/graph/badge.svg
-[badge_commits_since]: https://img.shields.io/github/commits-since/lunamorrow/mda_openbabel_converter/latest
-[badge_docs]: https://readthedocs.org/projects/mda_openbabel_converter/badge/?version=latest
+[badge_actions]: https://github.com/MDAnalysis/mda-openbabel-converter/actions/workflows/gh-ci.yaml/badge.svg
+[badge_codecov]: https://codecov.io/gh/MDAnalysis/mda-openbabel-converter/branch/main/graph/badge.svg
+[badge_commits_since]: https://img.shields.io/github/commits-since/MDAnalysis/mda-openbabel-converter/latest
+[badge_docs]: https://mda-openbabel-converter.readthedocs.io/en/latest/
 [badge_license]: https://img.shields.io/badge/License-GPLv2-blue.svg
 [badge_mda]: https://img.shields.io/badge/powered%20by-MDAnalysis-orange.svg?logoWidth=16&logo=data:image/x-icon;base64,AAABAAEAEBAAAAEAIAAoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJD+XwCY/fEAkf3uAJf97wGT/a+HfHaoiIWE7n9/f+6Hh4fvgICAjwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACT/yYAlP//AJ///wCg//8JjvOchXly1oaGhv+Ghob/j4+P/39/f3IAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJH8aQCY/8wAkv2kfY+elJ6al/yVlZX7iIiI8H9/f7h/f38UAAAAAAAAAAAAAAAAAAAAAAAAAAB/f38egYF/noqAebF8gYaagnx3oFpUUtZpaWr/WFhY8zo6OmT///8BAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgICAn46Ojv+Hh4b/jouJ/4iGhfcAAADnAAAA/wAAAP8AAADIAAAAAwCj/zIAnf2VAJD/PAAAAAAAAAAAAAAAAICAgNGHh4f/gICA/4SEhP+Xl5f/AwMD/wAAAP8AAAD/AAAA/wAAAB8Aov9/ALr//wCS/Z0AAAAAAAAAAAAAAACBgYGOjo6O/4mJif+Pj4//iYmJ/wAAAOAAAAD+AAAA/wAAAP8AAABhAP7+FgCi/38Axf4fAAAAAAAAAAAAAAAAiIiID4GBgYKCgoKogoB+fYSEgZhgYGDZXl5e/m9vb/9ISEjpEBAQxw8AAFQAAAAAAAAANQAAADcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAjo6Mb5iYmP+cnJz/jY2N95CQkO4pKSn/AAAA7gAAAP0AAAD7AAAAhgAAAAEAAAAAAAAAAACL/gsAkv2uAJX/QQAAAAB9fX3egoKC/4CAgP+NjY3/c3Nz+wAAAP8AAAD/AAAA/wAAAPUAAAAcAAAAAAAAAAAAnP4NAJL9rgCR/0YAAAAAfX19w4ODg/98fHz/i4uL/4qKivwAAAD/AAAA/wAAAP8AAAD1AAAAGwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALGxsVyqqqr/mpqa/6mpqf9KSUn/AAAA5QAAAPkAAAD5AAAAhQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADkUFBSuZ2dn/3V1df8uLi7bAAAATgBGfyQAAAA2AAAAMwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB0AAADoAAAA/wAAAP8AAAD/AAAAWgC3/2AAnv3eAJ/+dgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA9AAAA/wAAAP8AAAD/AAAA/wAKDzEAnP3WAKn//wCS/OgAf/8MAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIQAAANwAAADtAAAA7QAAAMAAABUMAJn9gwCe/e0Aj/2LAP//AQAAAAAAAAAA
-[badge_release]: https://img.shields.io/github/release-pre/lunamorrow/mda_openbabel_converter.svg
-[url_actions]: https://github.com/lunamorrow/mda_openbabel_converter/actions?query=branch%3Amain+workflow%3Agh-ci
-[url_codecov]: https://codecov.io/gh/lunamorrow/mda_openbabel_converter/branch/main
-[url_docs]: https://mda_openbabel_converter.readthedocs.io/en/latest/?badge=latest
-[url_latest_release]: https://github.com/lunamorrow/mda_openbabel_converter/releases
+[badge_release]: https://img.shields.io/github/release-pre/MDAnalysis/mda-openbabel-converter.svg
+[url_actions]: https://github.com/MDAnalysis/mda-openbabel-converter/actions?query=branch%3Amain+workflow%3Agh-ci
+[url_codecov]: https://codecov.io/gh/MDAnalysis/mda-openbabel-converter/branch/main
+[url_docs]: https://mda-openbabel-converter.readthedocs.io/en/latest/?badge=latest
+[url_latest_release]: https://github.com/MDAnalysis/mda-openbabel-converter/releases
 [url_license]: https://www.gnu.org/licenses/gpl-2.0
 [url_mda]: https://www.mdanalysis.org
 
 A package to convert between MDAnalysis and OpenBabel Objects
 
-mda-openbabel-converter is bound by a [Code of Conduct](https://github.com/lunamorrow/mda_openbabel_converter/blob/main/CODE_OF_CONDUCT.md).
+mda-openbabel-converter is bound by a [Code of Conduct](https://github.com/lunamorrow/mda-openbabel-converter/blob/main/CODE_OF_CONDUCT.md).
 
 ### Installation
 
@@ -34,22 +34,26 @@ If possible, we strongly recommend that you use
 Below we provide instructions both for `conda` and
 for `pip`.
 
+### Documentation
+
+The docs can be found [here] (https://mda-openbabel-converter.readthedocs.io/en/latest/)
+
 #### With conda
 
 Ensure that you have [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) installed.
 
 Create a virtual environment and activate it:
 
 ```
-conda create --name mda_openbabel_converter
-conda activate mda_openbabel_converter
+conda create --name mda-openbabel-converter
+conda activate mda-openbabel-converter
 ```
 
 Install the development and documentation dependencies:
 
 ```
-conda env update --name mda_openbabel_converter --file devtools/conda-envs/test_env.yaml
-conda env update --name mda_openbabel_converter --file docs/requirements.yaml
+conda env update --name mda-openbabel-converter --file devtools/conda-envs/test_env.yaml
+conda env update --name mda-openbabel-converter --file docs/requirements.yaml
 ```
 
 Build this package from source:
@@ -87,8 +91,8 @@ pip install ".[test,doc]"
 
 ### Copyright
 
-The mda-openbabel-converter source code is hosted at https://github.com/lunamorrow/mda_openbabel_converter
-and is available under the GNU General Public License, version 2 (see the file [LICENSE](https://github.com/lunamorrow/mda_openbabel_converter/blob/main/LICENSE)).
+The mda-openbabel-converter source code is hosted at https://github.com/lunamorrow/mda-openbabel-converter
+and is available under the GNU General Public License, version 2 (see the file [LICENSE](https://github.com/lunamorrow/mda-openbabel-converter/blob/main/LICENSE)).
 
 Copyright (c) 2024, Luna Morrow
 

docs/source/autosummary/mda_openbabel_converter.OpenBabel.rst

@@ -0,0 +1,13 @@
+mda\_openbabel\_converter.OpenBabel
+===================================
+
+.. automodule:: mda_openbabel_converter.OpenBabel
+
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      OpenBabelConverter
+      OpenBabelReader
+

docs/source/autosummary/mda_openbabel_converter.OpenBabelParser.rst

@@ -0,0 +1,12 @@
+mda\_openbabel\_converter.OpenBabelParser
+=========================================
+
+.. automodule:: mda_openbabel_converter.OpenBabelParser
+
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      OpenBabelParser
+

docs/source/autosummary/mda_openbabel_converter.data.files.rst

@@ -0,0 +1,6 @@
+mda\_openbabel\_converter.data.files
+====================================
+
+.. automodule:: mda_openbabel_converter.data.files
+
+

docs/source/autosummary/mda_openbabel_converter.data.rst

@@ -0,0 +1,13 @@
+mda\_openbabel\_converter.data
+==============================
+
+.. automodule:: mda_openbabel_converter.data
+
+
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   files

docs/source/autosummary/mda_openbabel_converter.rst

@@ -0,0 +1,15 @@
+mda\_openbabel\_converter
+=========================
+
+.. automodule:: mda_openbabel_converter
+
+
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   OpenBabel
+   OpenBabelParser
+   data

docs/source/conf.py

@@ -193,4 +193,5 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "mdanalysis": ("https://docs.mdanalysis.org/stable/", None),
+    "openbabel": ("https://openbabel.org/", None),
 }

mda_openbabel_converter/OpenBabel.py

@@ -1,5 +1,46 @@
-"""
-Documentation...
+"""OpenBabel molecule I/O --- :mod:`mda_openbabel_converter.OpenBabel`
+======================================================================
+
+Read coordinates data from an
+`OpenBabel <http://openbabel.org/api/3.0/classOpenBabel_1_1OBMol.shtml>`_
+:class:`openbabel.openbabel.OBMol` with :class:`OpenBabelReader` into an
+MDAnalysis Universe. Convert it back to a :class:`openbabel.openbabel.OBMol`
+with :class:`OpenBabelConverter`.
+
+Example
+-------
+
+To read an OpenBabel OBMol and then convert the AtomGroup back to an OpenBabel
+OBMol::
+
+    >>> from openbabel import openbabel as ob
+    >>> import MDAnalysis as mda
+    >>> obconversion = ob.OBConversion()
+    >>> obconversion.SetInFormat("pdb")
+    >>> mol = ob.OBMol()
+    >>> obconversion.ReadFile(mol, "1crn.pdb")
+    >>> u = mda.Universe(mol)
+    >>> u
+    <Universe with 327 atoms>
+    >>> u.trajectory
+    <OpenBabelReader with 1 frame of 327 atoms>
+    >>> u.atoms.convert_to("OPENBABEL")
+    <openbabel.openbabel.OBMol object at 0x7fcebb958148>
+
+
+.. warning::
+    The OpenBabel converter is currently *experimental* and may not work as
+    expected for all molecules.
+
+
+Classes
+-------
+
+.. autoclass:: OpenBabelReader
+   :members:
+
+.. autoclass:: OpenBabelConverter
+   :members:
 """
 
 import MDAnalysis as mda
@@ -22,9 +63,14 @@
 
 class OpenBabelReader(MemoryReader):
     """
+    Coordinate reader for OpenBabel.
+
     Inherits from MemoryReader and converts OpenBabel OBMol Coordinates to a
     MDAnalysis Trajectory which is used to build a Universe. This reader
-    does not work in the reverse direction.
+    does NOT work in the reverse direction.
+
+    See :class:`mda_openbabel_converter.OpenBabel.OpenBabelConverter` for
+    MDAnalysis Universe to OpenBabel OBMol conversion.
     """
     format = 'OPENBABEL'
 
@@ -77,7 +123,11 @@ def __init__(self, filename: OBMol, **kwargs):
 
 class OpenBabelConverter(ConverterBase):
     """
-    Convert a MDAnalysis AtomGroup to an OpenBabel OBMol
+    Inherits from ConverterBase and converts a MDAnalysis Universe to an
+    OpenBabel OBMol. This converter does NOT work in the opposite direction.
+
+    See :class:`mda_openbabel_converter.OpenBabelReader` for OpenBabel OBMol
+    to MDAnalysis Universe conversion.
     """
     def __repr__(self, **kwargs):
         """

mda_openbabel_converter/OpenBabelParser.py

@@ -1,5 +1,24 @@
 """
-Documentation...
+OpenBabel topology parser --- :mod:`mda_openbabel_converter.OpenBabel`
+======================================================================
+
+Converts an
+`OpenBabel <http://openbabel.org/api/3.0/classOpenBabel_1_1OBMol.shtml>`_
+:class:`openbabel.openbabel.OBMol` into a :class:`MDAnalysis.core.Topology`.
+
+
+See Also
+--------
+:mod:`mda_openbabel_converter.OpenBabel`
+
+
+Classes
+-------
+
+.. autoclass:: OpenBabelParser
+   :members:
+   :inherited-members:
+
 """
 
 import MDAnalysis as mda
@@ -46,9 +65,84 @@
 
 class OpenBabelParser(TopologyReaderBase):
     """
+    For OpenBabel structure
+
     Inherits from TopologyReaderBase and converts an OpenBabel OBMol to a
     MDAnalysis Topology or adds it to a pre-existing Topology. This parser
     does not work in the reverse direction.
+
+    For use examples, please see :class:`mda_openbabel_converter.OpenBabel`
+
+    Creates the following Attributes:
+     - Atomids
+     - Atomtypes
+     - Aromaticities
+     - Elements
+     - Masses
+     - Bonds
+     - Resids
+     - Resnums
+     - Segids
+
+    Depending on OpenBabel's input, the following Attributes might be present:
+     - Charges
+     - Resnames
+     - ICodes
+
+    Guesses the following:
+     - Atomnames
+
+    Missing Attributes unable to be retrieved from OpenBabel:
+     - Chiralities
+     - RSChirality
+     - Occupancies
+     - Tempfactors
+     - ChainIDs
+     - AltLocs
+
+    Attributes table:
+
+    +---------------------------------------------+-------------------------+
+    | OpenBabel attribute                         | MDAnalysis equivalent   |
+    +=============================================+=========================+
+    |                                             | altLocs                 |
+    +---------------------------------------------+-------------------------+
+    | atom.IsAromatic()                           | aromaticities           |
+    +---------------------------------------------+-------------------------+
+    |                                             | chainIDs                |
+    +---------------------------------------------+-------------------------+
+    | atom.GetPartialCharge()                     | charges                 |
+    +---------------------------------------------+-------------------------+
+    | GetSymbol(atom.GetAtomicNum())              | elements                |
+    +---------------------------------------------+-------------------------+
+    | atom.GetResidue().GetInsertionCode()        | icodes                  |
+    +---------------------------------------------+-------------------------+
+    | atom.GetIdx()                               | indices                 |
+    +---------------------------------------------+-------------------------+
+    | atom.GetExactMass()                         | masses                  |
+    +---------------------------------------------+-------------------------+
+    | "%s%d" % (GetSymbol(atom.GetAtomicNum()),   | names                   |
+    | atom.GetIdx())                              |                         |
+    +---------------------------------------------+-------------------------+
+    |                                             | chiralities             |
+    +---------------------------------------------+-------------------------+
+    |                                             | occupancies             |
+    +---------------------------------------------+-------------------------+
+    | atom.GetResidue().GetName()                 | resnames                |
+    +---------------------------------------------+-------------------------+
+    | atom.GetResidue().GetNum()                  | resnums                 |
+    +---------------------------------------------+-------------------------+
+    |                                             | tempfactors             |
+    +---------------------------------------------+-------------------------+
+    | atom.GetType()                              | types                   |
+    +---------------------------------------------+-------------------------+
+
+    Raises
+    ------
+    ValueError
+        If only some of the atoms have ResidueInfo, from resid.GetNum(),
+        available
+
     """
     format = 'OPENBABEL'
 
@@ -84,7 +178,6 @@ def parse(self, **kwargs):
         ids = []
         atomtypes = []
         segids = []
-        chainids = []
         icodes = []
 
         if mol.Empty():

mda_openbabel_converter/tests/conftest.py

@@ -2,11 +2,6 @@
 Global pytest fixtures
 """
 
-# Use this file if you need to share any fixtures
-# across multiple modules
-# More information at
-# https://docs.pytest.org/en/stable/how-to/fixtures.html#scope-sharing-fixtures-across-classes-modules-packages-or-session
-
 import pytest
 from mda_openbabel_converter.data.files import MDANALYSIS_LOGO
 

mda_openbabel_converter/tests/test_mda_openbabel_converter.py

@@ -1,8 +1,7 @@
 """
-Unit and regression test for the mda_openbabel_converter package.
+Base tests for the mda_openbabel_converter package.
 """
 
-# Import package, test suite, and other packages as needed
 import mda_openbabel_converter
 import pytest
 import sys

mda_openbabel_converter/tests/test_openbabel_parser.py

@@ -1,4 +1,8 @@
-# Testing OpenBabel and Pybel
+"""
+Test suite for the OpenBabel Parser that converts an OBMol's attributes to an
+MDAnalysis topology, alongside the OpenBabel Reader, that can be used to
+construct an MDAnalysis Universe.
+"""
 
 import MDAnalysis as mda
 import openbabel

mda_openbabel_converter/tests/test_openbabel_reader.py

@@ -1,4 +1,8 @@
-# Testing OpenBabel and Pybel
+"""
+Test suite for the OpenBabel Reader that converts an OBMol's atom coordinates
+to an MDAnalysis topology, alongside the OpenBabel Parser, that can be used to
+construct an MDAnalysis Universe.
+"""
 
 import MDAnalysis as mda
 import openbabel