Fixing issue with the documentation. (#152)

* Fixing issue with the documentation. The problem was that using the name md in for the molecular_dynamics workflow was causing the documentation to break. Hence the name was changed.

* Removing lammps test with version 2020.12.24 as it does not seems to be available to install via the github action.

* Updating the changelog

.github/workflows/ci.yml

@@ -37,8 +37,6 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - python-version: "3.9"
-            lammps-version: "2020.12.24"
           - python-version: "3.9"
             lammps-version: "2022.06.23"
           - python-version: "3.10"

.gitignore

@@ -45,3 +45,4 @@ pip-wheel-metadata
 docs/_build/
 docs/build
 docs/source/reference/api
+docs/source/apidocs

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+- Fixing an issue in the documentation caused by the fact that the molecular dynamics module file was called md, causing a confusion on whether it was the file extension of the actual file name. Changes the name of the file `src/aiida_lammps/workflows/md.py` for `src/aiida_lammps/workflows/molecular_dynamics.py`
+
 ## v1.0.2 2024-04-26
 
 - Fixing an issue in which some LAMMPS vectorial properties were not working properly.

docs/source/conf.py

@@ -24,15 +24,17 @@
 VERSION = __version__
 
 extensions = [
+    "myst_parser",
     "sphinx.ext.mathjax",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
+    "sphinx.ext.autodoc",
     "sphinx_click.ext",
     "sphinx_design",
-    "myst_parser",
+    "autodoc2",
+    "sphinx.ext.napoleon",
     "aiida.sphinxext",
-    "autoapi.extension",
 ]
 
 intersphinx_mapping = {
@@ -43,7 +45,7 @@
 }
 
 
-# Settings for the `autoapi.extenstion` automatically generating API docs
+# Settings for the `autoapi.extension` automatically generating API docs
 filepath_docs = pathlib.Path(__file__).parent.parent
 filepath_src = filepath_docs.parent / "src/aiida_lammps"
 autoapi_type = "python"
@@ -53,6 +55,26 @@
 autoapi_keep_files = True
 autoapi_add_toctree_entry = False
 
+autodoc2_packages = [
+    {
+        "path": "../../src/aiida_lammps",
+        "exclude_files": ["_docs.py"],
+        "auto_mode": True,
+    }
+]
+autodoc2_hidden_objects = ["dunder", "private", "inherited"]
+autodoc2_replace_annotations = [
+    ("re.Pattern", "typing.Pattern"),
+    ("markdown_it.MarkdownIt", "markdown_it.main.MarkdownIt"),
+]
+autodoc2_replace_bases = [
+    ("sphinx.directives.SphinxDirective", "sphinx.util.docutils.SphinxDirective"),
+]
+autodoc2_docstring_parser_regexes = [
+    ("myst_parser", "myst"),
+    (r"myst_parser\.setup", "myst"),
+]
+
 # Settings for the `sphinx_copybutton` extension
 copybutton_selector = "div:not(.no-copy)>div.highlight pre"
 copybutton_prompt_text = (

docs/source/index.md

@@ -30,7 +30,7 @@ developers/index
 ```{toctree}
 :hidden: true
 :caption: Reference
-reference/api/index
+apidocs/index
 ```
 
 

pyproject.toml

@@ -60,6 +60,7 @@ docs = [
     'sphinx-autoapi~=3.0',
     'myst_parser~=3.0.1',
     "furo",
+    "sphinx-autodoc2"
 ]
 
 pre-commit = ['pre-commit~=3.7']
@@ -79,7 +80,7 @@ pre-commit = ['pre-commit~=3.7']
 [project.entry-points."aiida.workflows"]
 "lammps.base" = "aiida_lammps.workflows.base:LammpsBaseWorkChain"
 "lammps.relax" = "aiida_lammps.workflows.relax:LammpsRelaxWorkChain"
-"lammps.md" = "aiida_lammps.workflows.md:LammpsMDWorkChain"
+"lammps.md" = "aiida_lammps.workflows.molecular_dynamics:LammpsMDWorkChain"
 
 [tool.flit.module]
 name = "aiida_lammps"

src/aiida_lammps/data/potential.py

@@ -72,7 +72,7 @@ def _validate_datetime(data: Union[str, int, float, datetime.datetime]) -> int:
     """
     Validate and transform dates into integers
 
-    :param data: representation of a year
+    param data: representation of a year
     :type data: Union[str,int,float, datetime.datetime]
     :raises TypeError: raise if the data is not of type str, int, float or datetime.datetime
     :return: integer representing a year
@@ -87,27 +87,27 @@ def _validate_datetime(data: Union[str, int, float, datetime.datetime]) -> int:
     return data
 
 
-def _validate_sources(data: Union[dict, list[dict]]) -> list[dict]:
+def _validate_sources(
+    data: Union[dict[str, Any], list[dict[str, Any]]],
+) -> list[dict[str, Any]]:
     """
     Validate the sources for the potential.
 
     This checks whether the entry is a dictionary that can be used to describe
     the citation for a potential.
 
     :param data: citation data for a potential
-    :type data: Union[dict, List[dict]]
+    :type data: Union[dict, List[dict[str, Any]]]
     :raises TypeError: raises if the data is not a dict or list of dicts
     :raises TypeError: raises if not all the entries in the list are dicts
     :return: list of references for a potential
-    :rtype: List[dict]
+    :rtype: List[dict[str, Any]]
     """
 
-    def _validate_single_source(source: dict) -> dict:
+    def _validate_single_source(source: dict[str, Any]) -> dict[str, Any]:
         """
         Validate a single potential citation data
-
         This will check if certain keys exists and add them to the citation data
-
         :param source: citation data for a potential
         :type source: dict
         :return: validated potential data
@@ -140,21 +140,12 @@ class LammpsPotentialData(orm.SinglefileData):
     """
     Base class for the LAMMPS potentials.
 
-    This class allows the storage/recovering of LAMMPS potentials, it allows
-    one to store any LAMMPS potential as a :py:class:`~aiida.orm.nodes.data.singlefile.SinglefileData` object, which can
-    then be either written to the LAMMPS input script and/or to a file, where
-    it can be easily read by LAMMPS. This distinction depends on the assigned
-    ``pair_style`` which require different ``pair_coeff`` entries in the input
-    file.
-
-    Based on the
-    `pseudo <https://github.com/aiidateam/aiida-pseudo/blob/master/aiida_pseudo/data/pseudo/pseudo.py>`_
-    class written by Sebaastian Huber.
-
-    The potentials are also tagged by following the KIM-API
-    `schema <https://openkim.org/doc/schema/kimspec/>`_, as to make them more easy
-    to track and as compatible as possible to the KIM schema.
-    """  # pylint: disable=line-too-long
+    This class allows the storage/recovering of LAMMPS potentials, it allows one to store any LAMMPS potential as a
+    :py:class:`~aiida.orm.nodes.data.singlefile.SinglefileData` object, which can then be either written to the LAMMPS
+    input script and/or to a file, where it can be easily read by LAMMPS.
+    This distinction depends on the assigned ``pair_style`` which require different ``pair_coeff`` entries in
+    the input file.
+    """
 
     # pylint: disable=too-many-arguments, too-many-ancestors
     _key_element = "element"
@@ -221,10 +212,8 @@ def get_or_create(
         :param extra_tags: Dictionary with extra information to tag the
             potential, based on the KIM schema.
         :type extra_tags: dict
-        :return: instance of ``LammpsPotentialData``, stored if taken from
-            database, unstored otherwise.
-        :raises TypeError: if the source is not a ``str``, ``pathlib.Path``
-            instance or binary stream.
+        :return: instance of ``LammpsPotentialData``, stored if taken from database, unstored otherwise.
+        :raises TypeError: if the source is not a ``str``, ``pathlib.Path`` instance or binary stream.
         :raises FileNotFoundError: if the source is a filepath but does not exist.
         """
         # pylint: disable=too-many-arguments
@@ -253,9 +242,10 @@ def get_or_create(
         return potential
 
     @classmethod
-    def get_entry_point_name(cls):
+    def get_entry_point_name(cls) -> str:
         """Return the entry point name associated with this data class.
         :return: the entry point name.
+        :rtype: str
         """
         _, entry_point = plugins.entry_point.get_entry_point_from_class(
             cls.__module__,
@@ -268,8 +258,9 @@ def is_readable_byte_stream(stream) -> bool:
         """Return if object is a readable filelike object in binary mode or stream of bytes.
 
         :param stream: the object to analyze.
-        :returns: True if ``stream`` appears to be a readable filelike object
+        :return: True if ``stream`` appears to be a readable filelike object
             in binary mode, False otherwise.
+        :rtype: bool
         """
         return isinstance(stream, io.BytesIO) or (
             hasattr(stream, "read") and hasattr(stream, "mode") and "b" in stream.mode
@@ -285,6 +276,8 @@ def prepare_source(cls, source: Union[str, pathlib.Path, BinaryIO]) -> BinaryIO:
         :raises TypeError: if the source is not a ``str``, ``pathlib.Path``
             instance or binary stream.
         :raises FileNotFoundError: if the source is a filepath but does not exist.
+        :return: byte stream with the potential information
+        :rtype: BinaryIO
         """
         if not isinstance(
             source, (str, pathlib.Path)
@@ -545,10 +538,10 @@ def pair_style(self) -> str:
         return self.base.attributes.get("pair_style")
 
     @property
-    def species(self) -> list:
+    def species(self) -> list[str]:
         """Return the list of species which this potential can be used for.
         :return: The list of chemical species which are contained in this potential.
-        :rtype: list
+        :rtype: list[str]
         """
         return self.base.attributes.get("species")
 
@@ -579,15 +572,15 @@ def content_origin(self) -> str:
         return self.base.attributes.get("content_origin")
 
     @property
-    def content_other_locations(self) -> Union[str, list]:
+    def content_other_locations(self) -> Union[str, list[str]]:
         """
         Return other locations where the potential can be found.
 
         As based in the KIM schema. A description of and/or web address(es)
         to other location(s) where the content is available.
 
         :return: other locations where the potential can be found.
-        :rtype: Union[str, list]
+        :rtype: Union[str, list[str]]
         """
         return self.base.attributes.get("content_other_locations")
 
@@ -621,7 +614,7 @@ def description(self) -> str:
         return self.base.attributes.get("description")
 
     @property
-    def developer(self) -> Union[str, list]:
+    def developer(self) -> Union[str, list[str]]:
         """
         Return the developer information of this potential.
 
@@ -632,7 +625,7 @@ def developer(self) -> Union[str, list]:
         of an interatomic model or a specific parameter set for it.
 
         :return: developer information of this potential
-        :rtype: Union[str, list]
+        :rtype: Union[str, list[str]]
         """
         return self.base.attributes.get("developer")
 
@@ -651,14 +644,14 @@ def disclaimer(self) -> str:
         return self.base.attributes.get("disclaimer")
 
     @property
-    def properties(self) -> Union[str, list]:
+    def properties(self) -> Union[str, list[str]]:
         """
         Return the properties for which this potential was devised.
 
         As based in the KIM schema. A list of properties reported by a KIM Item.
 
         :return: properties fow which this potential was devised.
-        :rtype: Union[str, list]
+        :rtype: Union[str, list[str]]
         """
         return self.base.attributes.get("properties")
 
@@ -675,15 +668,15 @@ def publication_year(self) -> Union[str, datetime.datetime, int]:
         return self.base.attributes.get("publication_year")
 
     @property
-    def source_citations(self) -> Union[str, list]:
+    def source_citations(self) -> Union[str, list[str]]:
         """
         Return the citation where the potential was originally published.
 
         As based in the KIM schema. An array of BibTeX-style EDN dictionaries
         corresponding to primary published work(s) describing the KIM Item.
 
         :return: the citation where the potential was originally published.
-        :rtype: Union[str, list]
+        :rtype: Union[str, list[str]]
         """
         return self.base.attributes.get("source_citations")
 

src/aiida_lammps/workflows/__init__.py

@@ -0,0 +1 @@
+"""Set of workflows to handle calculations using aiida-lammps"""