From 65e1bb419dc4f450d7aa129ee2bcfcd29599c87d Mon Sep 17 00:00:00 2001 From: Jonathan Chico <37243453+JPchico@users.noreply.github.com> Date: Thu, 12 Sep 2024 22:58:41 +0200 Subject: [PATCH] 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 | 2 - .gitignore | 1 + CHANGELOG.md | 2 + docs/source/conf.py | 28 +++++++- docs/source/index.md | 2 +- docs/source/reference/api/index.md | 11 --- pyproject.toml | 3 +- src/aiida_lammps/data/potential.py | 69 +++++++++---------- src/aiida_lammps/workflows/__init__.py | 1 + .../{md.py => molecular_dynamics.py} | 0 10 files changed, 63 insertions(+), 56 deletions(-) delete mode 100644 docs/source/reference/api/index.md rename src/aiida_lammps/workflows/{md.py => molecular_dynamics.py} (100%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e76c67cb..c71a5596 100644 --- a/.github/workflows/ci.yml +++ b/.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" diff --git a/.gitignore b/.gitignore index 3e725ab0..242d7f71 100644 --- a/.gitignore +++ b/.gitignore @@ -45,3 +45,4 @@ pip-wheel-metadata docs/_build/ docs/build docs/source/reference/api +docs/source/apidocs diff --git a/CHANGELOG.md b/CHANGELOG.md index 9705ddb9..a521196b 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/docs/source/conf.py b/docs/source/conf.py index 3057090c..6654b8c3 100644 --- a/docs/source/conf.py +++ b/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 = ( diff --git a/docs/source/index.md b/docs/source/index.md index e4285bd4..c14a19a4 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -30,7 +30,7 @@ developers/index ```{toctree} :hidden: true :caption: Reference -reference/api/index +apidocs/index ``` diff --git a/docs/source/reference/api/index.md b/docs/source/reference/api/index.md deleted file mode 100644 index 5d76d3ea..00000000 --- a/docs/source/reference/api/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Python API - -```{toctree} -:maxdepth: 3 -auto/aiida_lammps/utils/index -auto/aiida_lammps/calculations/index -auto/aiida_lammps/data/index -auto/aiida_lammps/parsers/index -auto/aiida_lammps/validation/index -auto/aiida_lammps/workflows/index -``` diff --git a/pyproject.toml b/pyproject.toml index 91bac58e..5e367a2d 100644 --- a/pyproject.toml +++ b/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" diff --git a/src/aiida_lammps/data/potential.py b/src/aiida_lammps/data/potential.py index 129c67da..61e3d218 100644 --- a/src/aiida_lammps/data/potential.py +++ b/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,7 +87,9 @@ 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. @@ -95,19 +97,17 @@ def _validate_sources(data: Union[dict, list[dict]]) -> list[dict]: 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 `_ - class written by Sebaastian Huber. - - The potentials are also tagged by following the KIM-API - `schema `_, 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,7 +572,7 @@ 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. @@ -587,7 +580,7 @@ def content_other_locations(self) -> Union[str, list]: 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,7 +668,7 @@ 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. @@ -683,7 +676,7 @@ def source_citations(self) -> Union[str, list]: 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") diff --git a/src/aiida_lammps/workflows/__init__.py b/src/aiida_lammps/workflows/__init__.py index e69de29b..1ec193ad 100644 --- a/src/aiida_lammps/workflows/__init__.py +++ b/src/aiida_lammps/workflows/__init__.py @@ -0,0 +1 @@ +"""Set of workflows to handle calculations using aiida-lammps""" diff --git a/src/aiida_lammps/workflows/md.py b/src/aiida_lammps/workflows/molecular_dynamics.py similarity index 100% rename from src/aiida_lammps/workflows/md.py rename to src/aiida_lammps/workflows/molecular_dynamics.py