Docs: update deps and general improvements

Some dependencies are updated to get the newer version of Myst-Nb, which was supporting only Sphinx < 6.0 and was generally problematic for e.g. pydantic module. A change of theme style is also applied, to stay on the same page as of aiida-qe in order to not confuse users with different layouts.
bastonero · Jul 26, 2023 · f6000d4 · f6000d4
1 parent f4e7048
commit f6000d4
Show file tree

Hide file tree

Showing 17 changed files with 57 additions and 110 deletions.
diff --git a/docs/source/citeus.md b/docs/source/citeus.md
@@ -0,0 +1,11 @@
+(citeus)=
+
+# Cite
+
+If you use this plugin for your research, please cite the following work:
+
+> Lorenzo Bastonero and Nicola Marzari, [*Automated all-functionals infrared and Raman spectra*](), **XXX**., **YYY**, **ZZZ** (2023)
+
+> Sebastiaan. P. Huber, Spyros Zoupanos, Martin Uhrin, Leopold Talirz, Leonid Kahle, Rico Häuselmann, Dominik Gresch, Tiziano Müller, Aliaksandr V. Yakutovich, Casper W. Andersen, Francisco F. Ramirez, Carl S. Adorf, Fernando Gargiulo, Snehal Kumbhar, Elsa Passaro, Conrad Johnston, Andrius Merkys, Andrea Cepellotti, Nicolas Mounet, Nicola Marzari, Boris Kozinsky, and Giovanni Pizzi, [*AiiDA 1.0, a scalable computational infrastructure for automated reproducible workflows and data provenance*](https://doi.org/10.1038/s41597-020-00638-4), Scientific Data **7**, 300 (2020)
+
+> 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://www.sciencedirect.com/science/article/pii/S0010465522001746), Computational Materials Science **187**, 110086 (2021)
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -25,7 +25,7 @@
 
 project = 'aiida-vibroscopy'
 copyright = ( # pylint: disable=redefined-builtin, line-too-long
-    f"""2022-{time.localtime().tm_year}, UNIVERSITY OF BREMEN, Germany. All rights reserved"""
+    f"""2023-{time.localtime().tm_year}, UNIVERSITY OF BREMEN, Germany. All rights reserved"""
 ) # pylint: disable=redefined-builtin, line-too-long
 
 # The full version, including alpha/beta/rc tags.
@@ -61,18 +61,18 @@
     'aiida_pseudo': ('https://aiida-pseudo.readthedocs.io/en/latest/', None),
     'aiida_phonopy': ('https://aiida-phonopy.readthedocs.io/en/latest/', None),
     'phonopy': ('https://phonopy.github.io/phonopy/', None),
-    'matplotlib': ('https://matplotlib.org/stable/index.html', None),
+    'matplotlib': ('https://matplotlib.org/stable/', None),
     'aiida_quantumespresso': ('https://aiida-quantumespresso.readthedocs.io/en/latest/', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master', None),
 }
 
 myst_enable_extensions = [
     'amsmath',
-    'colon_fence',
     'deflist',
+    'colon_fence',
+    'substitution',
     'dollarmath',
     'html_image',
-    'substitution',
 ]
 
 myst_substitutions = {
@@ -133,8 +133,9 @@
 # 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/bastonero/aiida-vibroscopy',
     'github_url': 'https://github.com/bastonero/aiida-vibroscopy',
     'use_edit_page_button': True,
 }
@@ -146,10 +147,13 @@
     '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_logo = 'images/logo_aiida.svg'
 html_static_path = ['_static']
 html_css_files = ['aiida-custom.css', 'aiida-qe-custom.css']
 
@@ -312,5 +316,6 @@
         r'phonopy.*',
         r'numpy.*',
         r'np.*',
+        r'pydantic.*',
     ]
 ]
diff --git a/docs/source/howto/index.md b/docs/source/howto/index.md
@@ -1,6 +1,6 @@
 (howto)=
 
-# How-to guides
+# How-tos
 
 :::{important}
 The following how-to guides assume that you are familiar with the basics of AiiDA and aiida-quantumespresso, such as creating data and running processes, as well as at least be able to run {class}`~aiida_quantumespresso.workflows.pw.base.PwBaseWorkChain` and {class}`~aiida_quantumespresso.workflows.pw.relax.PwRelaxWorkChain`.

diff --git a/docs/source/howto/postprocess.md b/docs/source/howto/postprocess.md
@@ -4,7 +4,7 @@
 
 Here you will find some _how-tos_ on how to post-process the `VibrationalData` and `PhonopyData`.
 These can be generated via the `HarmonicWorkChain`, the `IRamanSpectraWorkChain` or the `PhononWorkChain`.
-Please, have a look at the [tutorials](tutorials) for an overview, and at the specific [topics](topics) sections.
+Please, have a look at the [tutorials](tutorials) for an overview, and at the specific topics section.
 
 ::: {hint}
 You can always access to the detailed description of a function/method putting a `?` question mark in front

diff --git a/docs/source/howto/understand.md b/docs/source/howto/understand.md
@@ -4,7 +4,7 @@
 
 In AiiDA the CalcJobs and WorkChains have usually nested inputs and different options on how to run the calculation
 and/or workflows. To understand the nested input structure of CalcJobs/Workflows, we made them available in a clickable
-fashion in the [topics section](topics).
+fashion in the topics section.
 
 Moreover, it could be useful to understand the
 [_expose inputs/outputs_](https://aiida.readthedocs.io/projects/aiida-core/en/latest/topics/workflows/usage.html#modular-workflow-design)

diff --git a/docs/source/images/BIG-MAP_logo.png b/docs/source/images/BIG-MAP_logo.png
diff --git a/docs/source/images/MARVEL.png b/docs/source/images/MARVEL.png
diff --git a/docs/source/images/MaX.png b/docs/source/images/MaX.png
diff --git a/docs/source/images/logo_aiida_quantumespresso.png b/docs/source/images/logo_aiida_quantumespresso.png
diff --git a/docs/source/images/logo_docs.png b/docs/source/images/logo_docs.png
diff --git a/docs/source/images/qe_logo.jpg b/docs/source/images/qe_logo.jpg
diff --git a/docs/source/images/swissuniversities.png b/docs/source/images/swissuniversities.png
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -11,43 +11,44 @@ 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 guides
+
+howto/index
+citeus
+```
 
-:::{grid-item}
-:columns: 12 4 4 4
+```{toctree}
+:hidden: true
+:caption: Topic guides
 
-```{image} images/logo_aiida_quantumespresso.png
-:width: 200px
-:class: sd-m-auto
+topics/workflows/index
+topics/formulation
+topics/overrides
+topics/conventions
 ```
-:::
 
-:::{grid-item}
-:columns: 12 8 8 8
-:child-align: justify
-:class: sd-fs-5
+```{toctree}
+:hidden: true
+:caption: Reference
+
+reference/index
+```
 
 # AiiDA Vibroscopy
 
 An AiiDA plugin package for the calculation of __infrared__ and __Raman__ spectra and __harmonic phonons__ using [Quantum ESPRESSO](http://www.quantumespresso.org) and [Phonopy](https://phonopy.github.io/phonopy/). Compute ab-initio vibrational properties in automated fashion and with the use of any functional (and pseudo-potential formalism as well!), such as traditional LDA and GGAs, extended Hubbard functionals, hybrids and more!
 
-**aiida-vibroscopy version:** {{ release }}
-
-:::
-
-::::
+[![PyPI version](https://badge.fury.io/py/aiida-vibroscopy.svg)](https://badge.fury.io/py/aiida-vibroscopy)
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/aiida-vibroscopy.svg)](https://pypi.python.org/pypi/aiida-vibroscopy)
+[![Build Status](https://github.com/bastonero/aiida-vibroscopy/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bastonero/aiida-vibroscopy/actions)
+[![Docs status](https://readthedocs.org/projects/aiida-vibroscopy/badge)](http://aiida-vibroscopy.readthedocs.io/)
 
 ______________________________________________________________________
 
@@ -93,62 +94,6 @@ 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_vibroscopy/index
-:ref-type: doc
-:click-parent:
-:expand:
-:color: primary
-:outline:
-
-To the reference guides
-```
-:::
 ::::
 
 (cite)=
@@ -157,7 +102,7 @@ To the reference guides
 
 If you use this plugin for your research, please cite the following work:
 
-> Lorenzo Bastonero and Nicola Marzari, [*Automated all-functionals infrared and Raman spectra*](), npj Comp. Mat., **?**, ? (2023)
+> Lorenzo Bastonero and Nicola Marzari, [*Automated all-functionals infrared and Raman spectra*](), **XXX**., **YYY**, **ZZZ** (2023)
 
 > Sebastiaan. P. Huber, Spyros Zoupanos, Martin Uhrin, Leopold Talirz, Leonid Kahle, Rico Häuselmann, Dominik Gresch, Tiziano Müller, Aliaksandr V. Yakutovich, Casper W. Andersen, Francisco F. Ramirez, Carl S. Adorf, Fernando Gargiulo, Snehal Kumbhar, Elsa Passaro, Conrad Johnston, Andrius Merkys, Andrea Cepellotti, Nicolas Mounet, Nicola Marzari, Boris Kozinsky, and Giovanni Pizzi, [*AiiDA 1.0, a scalable computational infrastructure for automated reproducible workflows and data provenance*](https://doi.org/10.1038/s41597-020-00638-4), Scientific Data **7**, 300 (2020)
 

diff --git a/docs/source/topics/index.md b/docs/source/topics/index.md
diff --git a/pyproject.toml b/pyproject.toml
@@ -47,15 +47,15 @@ tests = [
     'pytest-regressions~=2.3',
 ]
 docs = [
-    'myst-nb~=0.17',
-    'jupytext>=1.11.2,<1.15.0',
-    'sphinx-togglebutton',
-    'sphinx~=5.2',
+    'myst-nb@git+https://github.com/executablebooks/MyST-NB.git',
+    'sphinx~=6.2.1',
     'sphinx-copybutton~=0.5.2',
     'sphinx-book-theme~=1.0.1',
     'sphinx-design~=0.4.1',
     'sphinxcontrib-details-directive~=0.1.0',
-    'sphinx-autoapi~=2.0.1'
+    'sphinx-autoapi~=2.0.1',
+    'myst_parser~=1.0.0',
+    'sphinx-togglebutton',
 ]
 
 [project.entry-points.'aiida.data']

diff --git a/src/aiida_vibroscopy/calculations/phonon_utils.py b/src/aiida_vibroscopy/calculations/phonon_utils.py
@@ -15,9 +15,7 @@
 
 from aiida import orm
 from aiida.engine import calcfunction
-from aiida.plugins import DataFactory
-
-PreProcessData = DataFactory('phonopy.preprocess')
+from aiida_phonopy.data.preprocess import PreProcessData
 
 
 @calcfunction

diff --git a/src/aiida_vibroscopy/utils/plotting.py b/src/aiida_vibroscopy/utils/plotting.py
@@ -31,7 +31,7 @@ def get_spectra_plot(
     :param broadening_function: multi broadening function
     :param normalize: whether normalize the spectra to have maximum peak to 1
 
-    :return: :class:`matplotlib.pyplot`
+    :return: :mod:`matplotlib.pyplot`
     """
     import matplotlib.pyplot as plt
     from matplotlib.ticker import AutoMinorLocator