diff --git a/.gitignore b/.gitignore index da1f17741..c47e0504b 100644 --- a/.gitignore +++ b/.gitignore @@ -111,4 +111,4 @@ ENV/ submit_test/ # Autogenerated API docs -docs/source/reference/api/aiida_quantumespresso +docs/source/reference/api/auto diff --git a/docs/Makefile b/docs/Makefile index af76c6f1f..20f595cd5 100755 --- a/docs/Makefile +++ b/docs/Makefile @@ -24,7 +24,7 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source customdefault: $(SPHINXBUILD) -b html -nW --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html -all: html view +all: clean html view clean: rm -rf $(BUILDDIR) @@ -34,6 +34,5 @@ html: @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - view: open $(BUILDDIR)/html/index.html diff --git a/docs/source/_static/aiida-qe-custom.css b/docs/source/_static/aiida-qe-custom.css index 3d37cd7f7..fc02e48e1 100644 --- a/docs/source/_static/aiida-qe-custom.css +++ b/docs/source/_static/aiida-qe-custom.css @@ -11,18 +11,29 @@ font-size: 140%; } -div.navbar-brand-box a.navbar-brand img { - display: block; - height: auto; - width: auto; - max-height: 100vh; - max-width: 90%; - margin: 0 auto; - padding-left: 30px +.navbar-brand { + padding: 0; + padding-top: 0.5rem; +} + +img.logo__image { + max-height: 180px; + padding-left: 1.5rem; + padding-bottom: 1rem; +} + +.navbar-icon-links i.fa-brands { + font-size: 40px!important; +} + +img.aiida-logo { + height: 40px!important; +} + +.fa { + color: var(--pst-color-primary); } -@media (min-width: 768px) { - div.navbar-brand-box a.navbar-brand img { - max-height: 100vh !important - } +.bd-search { + padding: 0 1rem; } diff --git a/docs/source/images/logo_aiida.svg b/docs/source/_static/logo_aiida.svg similarity index 100% rename from docs/source/images/logo_aiida.svg rename to docs/source/_static/logo_aiida.svg diff --git a/docs/source/_static/logo_aiida_quantumespresso-dark.png b/docs/source/_static/logo_aiida_quantumespresso-dark.png new file mode 100644 index 000000000..57ba96b49 Binary files /dev/null and b/docs/source/_static/logo_aiida_quantumespresso-dark.png differ diff --git a/docs/source/images/logo_aiida_quantumespresso.png b/docs/source/_static/logo_aiida_quantumespresso-light.png similarity index 100% rename from docs/source/images/logo_aiida_quantumespresso.png rename to docs/source/_static/logo_aiida_quantumespresso-light.png diff --git a/docs/source/_templates/icon-links.html b/docs/source/_templates/icon-links.html new file mode 100644 index 000000000..8ec32e8c0 --- /dev/null +++ b/docs/source/_templates/icon-links.html @@ -0,0 +1,40 @@ +{%- macro icon_link_nav_item(url, icon, name, type, attributes='') -%} + {%- if url | length > 2 %} +
  • + {%- set attributesDefault = { "href": url, "title": name, "class": "nav-link", "rel": "noopener", "target": "_blank", "data-bs-toggle": "tooltip", "data-bs-placement": "bottom"} %} + {%- if attributes %}{% for key, val in attributes.items() %} + {% set _ = attributesDefault.update(attributes) %} + {% endfor %}{% endif -%} + {% set attributeString = [] %} + {% for key, val in attributesDefault.items() %} + {%- set _ = attributeString.append('%s="%s"' % (key, val)) %} + {% endfor %} + {% set attributeString = attributeString | join(" ") -%} + + {%- if type == "fontawesome" -%} + + {{ name }} + {%- elif type == "local" -%} + {{ name }} + {%- elif type == "url" -%} + {{ name }} + {%- else %} + Incorrectly configured icon link. Type must be `fontawesome`, `url` or `local`. + {%- endif -%} + +
    • + {%- endif -%} +{%- endmacro -%} +{%- if theme_icon_links -%} + +{%- endif -%} diff --git a/docs/source/_templates/sbt-sidebar-nav.html b/docs/source/_templates/sbt-sidebar-nav.html new file mode 100644 index 000000000..e9bbe7b66 --- /dev/null +++ b/docs/source/_templates/sbt-sidebar-nav.html @@ -0,0 +1,24 @@ + diff --git a/docs/source/conf.py b/docs/source/conf.py index da595a69e..3be770690 100755 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -14,16 +14,12 @@ import pathlib import time -# Load the dummy profile even if we are running locally, this way the documentation will succeed even if the current -# default profile of the AiiDA installation does not use a Django backend. from aiida.manage.configuration import load_documentation_profile +load_documentation_profile() # If extensions (or modules to document with autodoc) are in another directory, # 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 aiida_quantumespresso - -load_documentation_profile() # -- Project information ----------------------------------------------------- @@ -32,11 +28,6 @@ Materials (THEOS) and National Centre for Computational Design and Discovery of Novel Materials (NCCR MARVEL)), Switzerland. All rights reserved""" -# The full version, including alpha/beta/rc tags. -release = aiida_quantumespresso.__version__ -# The short X.Y version. -version = '.'.join(aiida_quantumespresso.__version__.split('.')[:2]) - # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. @@ -46,7 +37,6 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode', @@ -61,9 +51,8 @@ # Setting the intersphinx mapping to other readthedocs intersphinx_mapping = { 'python': ('https://docs.python.org/3.8', None), - 'aiida': ('https://aiida.readthedocs.io/en/latest/', None), + 'aiida': ('https://aiida.readthedocs.io/projects/aiida-core/en/latest/', None), 'aiida_pseudo': ('http://aiida-pseudo.readthedocs.io/en/latest/', None), - 'sphinx': ('https://www.sphinx-doc.org/en/master', None), } myst_enable_extensions = [ @@ -72,18 +61,13 @@ 'substitution' ] -myst_substitutions = { - 'release': release, - 'version': version -} - # Settings for the `autoapi.extenstion` automatically generating API docs filepath_docs = pathlib.Path(__file__).parent.parent filepath_src = filepath_docs.parent / 'src' autoapi_type = 'python' autoapi_dirs = [filepath_src] autoapi_ignore = [filepath_src / 'aiida_quantumespresso' / '*cli*'] -autoapi_root = str(filepath_docs / 'source' / 'reference' / 'api') +autoapi_root = str(filepath_docs / 'source' / 'reference' / 'api' / 'auto') autoapi_keep_files = True autoapi_add_toctree_entry = False @@ -104,18 +88,24 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +exclude_patterns = ['**.ipynb_checkpoints', 'reference/api/auto/aiida_quantumespresso/index.rst'] # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'pydata_sphinx_theme' +html_theme = 'sphinx_book_theme' html_theme_options = { + 'repository_url': 'https://github.com/aiidateam/aiida-quantumespresso', 'github_url': 'https://github.com/aiidateam/aiida-quantumespresso', 'twitter_url': 'https://twitter.com/aiidateam', 'use_edit_page_button': True, + 'logo': { + 'text': 'AiiDA Quantum ESPRESSO', + 'image_light': '_static/logo_aiida_quantumespresso-light.png', + 'image_dark': '_static/logo_aiida_quantumespresso-dark.png', + } } html_static_path = ['_static'] html_context = { @@ -125,10 +115,12 @@ 'doc_path': 'docs/source', 'default_mode': 'light', } +html_sidebars = { + '**': ['navbar-logo.html', 'navbar-icon-links.html', 'search-field.html', 'sbt-sidebar-nav.html'] +} # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = 'images/logo_docs.png' html_static_path = ['_static'] html_css_files = ['aiida-custom.css', 'aiida-qe-custom.css'] @@ -146,80 +138,18 @@ # Output file base name for HTML help builder. htmlhelp_basename = 'aiida-quantumespressodoc' -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - #'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - #'preamble': '', - - # Latex figure (float) alignment - #'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -# latex_documents = [ -# ] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -# man_pages = [ -# ] - -# If true, show URL addresses after external links. -#man_show_urls = False - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -# texinfo_documents = [ -# ] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False +# ------------------------------------------------------------------------------ # Warnings to ignore when using the -n (nitpicky) option # We should ignore any python built-in exception, for instance +nitpicky = True + +nitpick_ignore_regex = [ + (r'py:.*', r'pydantic.*'), + (r'py:.*', r'con.*'), + (r'.*', r'Literal.*'), + (r'.*', r'Tuple.*'), +] nitpick_ignore = [ ('py:exc', 'ArithmeticError'), ('py:exc', 'AssertionError'), diff --git a/docs/source/howto/calculations/index.md b/docs/source/howto/calculations/index.md index af2e7d221..8b8ab4e3f 100644 --- a/docs/source/howto/calculations/index.md +++ b/docs/source/howto/calculations/index.md @@ -1,6 +1,11 @@ (howto-calculations)= -# How-to run calculations +# Calculations + +:::{important} +The following how-to guides assume that you are familiar with the basics of AiiDA, such as creating data and running processes. +At the very least, make sure you have followed and understand the tutorial on [running a calculation through the API](#tutorials-pw-through-api). +::: ```{toctree} :maxdepth: 1 diff --git a/docs/source/howto/index.md b/docs/source/howto/index.md deleted file mode 100644 index f02b823af..000000000 --- a/docs/source/howto/index.md +++ /dev/null @@ -1,13 +0,0 @@ -# How-to guides - -:::{important} -The following how-to guides assume that you are familiar with the basics of AiiDA, such as creating data and running processes. -At the very least, make sure you have followed and understand the tutorial on [running a calculation through the API](#tutorials-pw-through-api). -::: - -```{toctree} -:maxdepth: 2 - -calculations/index -workflows/index -``` diff --git a/docs/source/howto/workflows/index.md b/docs/source/howto/workflows/index.md index 4031539bf..1b88f4f27 100644 --- a/docs/source/howto/workflows/index.md +++ b/docs/source/howto/workflows/index.md @@ -1,6 +1,6 @@ (howto-workflows)= -# How-to run workflows +# Workflows ```{toctree} :maxdepth: 1 diff --git a/docs/source/index.md b/docs/source/index.md index 590604e13..4a4f99456 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -8,33 +8,32 @@ myst: ```{toctree} :hidden: true -:maxdepth: 2 installation/index tutorials/index -howto/index -topics/index -reference/index ``` -::::{grid} -:reverse: -:gutter: 2 3 3 3 -:margin: 1 2 1 2 +```{toctree} +:hidden: true +:caption: How to -:::{grid-item} -:columns: 12 4 4 4 +howto/calculations/index +howto/workflows/index +``` -```{image} images/logo_aiida_quantumespresso.png -:width: 200px -:class: sd-m-auto +```{toctree} +:hidden: true +:caption: Topic guides +topics/calculations/index +topics/workflows/index ``` -::: -:::{grid-item} -:columns: 12 8 8 8 -:child-align: justify -:class: sd-fs-5 +```{toctree} +:hidden: true +:caption: Reference +reference/api/index +reference/cli/index +``` # AiiDA Quantum ESPRESSO @@ -42,11 +41,10 @@ An AiiDA plugin package to integrate the [Quantum ESPRESSO](http://www.quantumes Compute a variety of material properties with the popular open source DFT code with automatic data provenance provided by AiiDA. Geometry optimizations, ground-state electronic structure, band structures, phonons, and much more. -**aiida-quantumespresso version:** {{ release }} - -::: - -:::: +[![PyPI version](https://badge.fury.io/py/aiida-quantumespresso.svg)](https://badge.fury.io/py/aiida-quantumespresso) +[![PyPI pyversions](https://img.shields.io/pypi/pyversions/aiida-quantumespresso.svg)](https://pypi.python.org/pypi/aiida-quantumespresso) +[![Build Status](https://github.com/aiidateam/aiida-quantumespresso/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/aiidateam/aiida-quantumespresso/actions) +[![Docs status](https://readthedocs.org/projects/aiida-quantumespresso/badge)](http://aiida-quantumespresso.readthedocs.io/) ______________________________________________________________________ @@ -91,67 +89,10 @@ Easy examples to take the first steps with the plugin package. To the tutorials ``` ::: - -:::{grid-item-card} {fa}`question-circle;mr-1` How-to guides -:text-align: center -:shadow: md - -Hands-on guides to achieve specific goals. - -+++ - -```{button-ref} howto/index -:ref-type: doc -:click-parent: -:expand: -:color: primary -:outline: - -To the how-to guides -``` -::: - -:::{grid-item-card} {fa}`bookmark;mr-1` Topic guides -:text-align: center -:shadow: md - -Detailed background information on various concepts. - -+++ - -```{button-ref} topics/index -:ref-type: doc -:click-parent: -:expand: -:color: primary -:outline: - -To the topic guides -``` -::: - -:::{grid-item-card} {fa}`cogs;mr-1` Reference guides -:text-align: center -:shadow: md - -Detailed reference guides on the application programming and command line interfaces. - -+++ - -```{button-ref} reference/api/aiida_quantumespresso/index -:ref-type: doc -:click-parent: -:expand: -:color: primary -:outline: - -To the reference guides -``` -::: :::: -# How to cite +## How to cite If you use this plugin for your research, please cite the following work: @@ -161,7 +102,7 @@ If you use this plugin for your research, please cite the following work: > Martin Uhrin, Sebastiaan. P. Huber, Jusong Yu, Nicola Marzari, and Giovanni Pizzi, [*Workflows in AiiDA: Engineering a high-throughput, event-based engine for robust and modular computational workflows*](https://doi.org/10.1016/j.commatsci.2020.110086), Computational Materials Science **187**, 110086 (2021) -# Acknowledgements +## Acknowledgements We acknowledge support from: diff --git a/docs/source/reference/api/index.md b/docs/source/reference/api/index.md new file mode 100644 index 000000000..be9559d31 --- /dev/null +++ b/docs/source/reference/api/index.md @@ -0,0 +1,12 @@ +# Python API + +```{toctree} +:maxdepth: 3 +auto/aiida_quantumespresso/calculations/index +auto/aiida_quantumespresso/common/index +auto/aiida_quantumespresso/data/index +auto/aiida_quantumespresso/parsers/index +auto/aiida_quantumespresso/tools/index +auto/aiida_quantumespresso/utils/index +auto/aiida_quantumespresso/workflows/index +``` diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md deleted file mode 100644 index 10af28e47..000000000 --- a/docs/source/reference/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# Reference - -```{toctree} -:hidden: true -:maxdepth: 2 - -api/aiida_quantumespresso/index -cli/index -``` diff --git a/docs/source/topics/index.md b/docs/source/topics/index.md deleted file mode 100644 index 7b69f598e..000000000 --- a/docs/source/topics/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# Topic guides - -```{toctree} -:maxdepth: 2 - -calculations/index -workflows/index -``` diff --git a/src/aiida_quantumespresso/common/hubbard.py b/src/aiida_quantumespresso/common/hubbard.py index 2682a18ab..99ddca3eb 100644 --- a/src/aiida_quantumespresso/common/hubbard.py +++ b/src/aiida_quantumespresso/common/hubbard.py @@ -85,7 +85,7 @@ def to_tuple(self) -> Tuple[int, str, int, str, float, Tuple[int, int, int], str @staticmethod def from_tuple(hubbard_parameters: Tuple[int, str, int, str, float, Tuple[int, int, int], str]): - """Return a :meth:`~aiida_quantumespresso.common.hubbard.HubbardParameters` instance from a list. + """Return a ``HubbardParameters`` instance from a list. The parameters within the list must have the following order: * atom_index @@ -112,7 +112,7 @@ class Hubbard(BaseModel): """Class for complete description of Hubbard interactions.""" parameters: List[HubbardParameters] - """List of :meth:`~aiida_quantumespress.common.hubbard.HubbardParameters`.""" + """List of :class:`~aiida_quantumespresso.common.hubbard.HubbardParameters`.""" projectors: Literal['atomic', 'ortho-atomic', diff --git a/src/aiida_quantumespresso/data/hubbard_structure.py b/src/aiida_quantumespresso/data/hubbard_structure.py index 71a2fe32f..041aac199 100644 --- a/src/aiida_quantumespresso/data/hubbard_structure.py +++ b/src/aiida_quantumespresso/data/hubbard_structure.py @@ -30,7 +30,7 @@ def __init__( :param pbc: (3,) shape list in bools :param sites: list of lists, each of the shape [symbol, name, position], where position is a (3,) shape list of floats - :param hubbard: a :py:meth:`~aiida_quantumespresso.common.hubbrd.Hubbard` istance + :param hubbard: a :class:`~aiida_quantumespresso.common.hubbard.Hubbard` istance """ super().__init__(cell=cell, **kwargs) self.sites = sites @@ -39,12 +39,12 @@ def __init__( @property def sites(self): - """Return the :meth:`aiida.core.Sites`.""" + """Return the :attr:`~aiida.orm.nodes.data.structure.StructureData.sites`.""" return super().sites @sites.setter def sites(self, values: List[Tuple[str, str, Tuple[float, float, float]]]): - """Set the :meth:`aiida.core.Sites`. + """Set the :attr:`~aiida.orm.nodes.data.structure.StructureData.sites`. :param values: list of sites, each as [symbol, name, (3,) shape list of positions] """ @@ -56,7 +56,7 @@ def sites(self, values: List[Tuple[str, str, Tuple[float, float, float]]]): def hubbard(self) -> Hubbard: """Get the `Hubbard` instance. - :returns: a :py:meth:`~aiida_quantumespresso.common.hubbard.Hubbard` instance. + :returns: a :class:`~aiida_quantumespresso.common.hubbard.Hubbard` instance. """ with self.base.repository.open(self._hubbard_filename, mode='rb') as handle: return Hubbard.parse_raw(json.load(handle)) @@ -77,8 +77,8 @@ def from_structure( ): """Return an instance of ``HubbardStructureData`` from a ``StructureData`` node. - :param structure: :meth:`aiida.orm.StructureData` instance - :param hubbad: :meth:`~aiida_quantumespresso.common.hubbard.Hubbard` instance + :param structure: :class:`aiida.orm.StructureData` instance + :param hubbard: :class:`~aiida_quantumespresso.common.hubbard.Hubbard` instance :returns: ``HubbardStructureData`` instance """ sites = [[structure.get_kind(site.kind_name).symbol, site.kind_name, site.position] for site in structure.sites] @@ -97,7 +97,7 @@ def append_hubbard_parameter( translation: Tuple[int, int, int] = None, hubbard_type: str = 'Ueff', ): - """Append a :meth:`~aiida_quantumespresso.common.hubbard.HubbardParameters``. + """Append a :class:`~aiida_quantumespresso.common.hubbard.HubbardParameters`. :param atom_index: atom index in unitcell :param atom_manifold: atomic manifold (e.g. 3d, 3d-2p) @@ -107,7 +107,7 @@ def append_hubbard_parameter( :param translation: (3,) list of ints, describing the translation vector associated with the neighbour atom, defaults to None :param hubbard_type: hubbard type (U, V, J, ...), defaults to 'Ueff' - (see :meth:`~aiida_quantumespresso.common.hubbard.Hubbard` for full allowed values) + (see :class:`~aiida_quantumespresso.common.hubbard.Hubbard` for full allowed values) """ pymat = self.get_pymatgen_structure() sites = pymat.sites @@ -161,7 +161,7 @@ def initialize_intersites_hubbard( :param neighbour_manifold: neighbour manifold (e.g. 3d, 3d-2p) :param value: value of the Hubbard parameter, in eV :param hubbard_type: hubbard type (U, V, J, ...), defaults to 'V' - (see :meth:`~aiida_quantumespresso.common.hubbard.Hubbard` for full allowed values) + (see :class:`~aiida_quantumespresso.common.hubbard.Hubbard` for full allowed values) :param use_kinds: whether to use kinds for initializing the parameters; when False, it initializes all the ``Kinds`` matching the ``atom_name`` """ @@ -197,7 +197,7 @@ def initialize_onsites_hubbard( :param atom_manifold: atomic manifold (e.g. 3d, 3d-2p) :param value: value of the Hubbard parameter, in eV :param hubbard_type: hubbard type (U, J, ...), defaults to 'Ueff' - (see :meth:`~aiida_quantumespresso.common.hubbard.Hubbard` for full allowed values) + (see :class:`~aiida_quantumespresso.common.hubbard.Hubbard` for full allowed values) :param use_kinds: whether to use kinds for initializing the parameters; when False, it initializes all the ``Kinds`` matching the ``atom_name`` """ diff --git a/src/aiida_quantumespresso/utils/hubbard.py b/src/aiida_quantumespresso/utils/hubbard.py index 62cedacd1..046488fd5 100644 --- a/src/aiida_quantumespresso/utils/hubbard.py +++ b/src/aiida_quantumespresso/utils/hubbard.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -"""Utility class for handling the :class:`data.hubbard_structure.HubbardStructureData`.""" +"""Utility class for handling the :class:`aiida_quantumespresso.data.hubbard_structure.HubbardStructureData`.""" # pylint: disable=no-name-in-module from itertools import product import os