Fix documentation

.github/workflows/gh-pages.yml

@@ -37,29 +37,29 @@ jobs:
             conda create -n abipy python=${{ matrix.config.python }} --yes
             conda activate abipy
             conda install abinit -c conda-forge --yes
-            abinit --version
-            abinit --build
+            mpirun -n 1 abinit --version
+            mpirun -n 1 abinit --build
             pip install . # --editable
             mkdir -p $HOME/.abinit/abipy/
             cp abipy/data/managers/travis_manager.yml $HOME/.abinit/abipy/manager.yml
             cp abipy/data/managers/simple_scheduler.yml $HOME/.abinit/abipy/scheduler.yml
 
       - name: Build docs with Sphinx
         run: |
-            cd docs
-            pip install -r requirements.txt
-            make -j
+            cd docs 
+            source install.sh
+            make
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v2
 
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v2
+  #deploy:
+  #  environment:
+  #    name: github-pages
+  #    url: ${{ steps.deployment.outputs.page_url }}
+  #  runs-on: ubuntu-latest
+  #  needs: build
+  #  steps:
+  #    - name: Deploy to GitHub Pages
+  #      id: deployment
+  #      uses: actions/deploy-pages@v2

abipy/abio/robots.py

@@ -967,7 +967,7 @@ def plot_convergence(self, item: Union[str, Callable],
                 Accepts callable or string.
                 If string, it's assumed that the abifile has an attribute with the same name and getattr is invoked.
                 If callable, the output of hue(abifile) is used.
-            abs_conv: If not None, plot f(x) and |f(x) - f(x_inf)| in log scale.
+            abs_conv: If not None, plot f(x) and abs(f(x) - f(x_inf)) in log scale.
             ax: |matplotlib-Axes| or None if a new figure should be created.
             fontsize: legend and label fontsize.
             kwargs: keyword arguments passed to matplotlib plot method.
@@ -1044,7 +1044,7 @@ def plot_convergence_items(self, items: list[Union[str, Callable]],
                 If string, it's assumed that the abifile has an attribute with the same name and getattr is invoked.
                 Dot notation is also supported e.g. hue="structure.formula" --> abifile.structure.formula
                 If callable, the output of hue(abifile) is used.
-            abs_conv: If not None, plot f(x) and |f(x) - f(x_inf)| in log scale.
+            abs_conv: If not None, plot f(x) and abs(f(x) - f(x_inf)) in log scale.
                 Since we are plotting multiple quantities, abs_conv is a dict mapping the name of the item to
                 to the convergence.
             fontsize: legend and label fontsize.

abipy/core/func1d.py

@@ -540,7 +540,7 @@ def plotly_traces(self, fig, rcd=None, exchange_xy=False, xfactor=1, yfactor=1,
         Helper function to plot the function with plotly.
 
         Args:
-            fig: |plotly.graph_objects.Figure|.
+            fig: plotly.graph_objects.Figure.
             rcd: PlotlyRowColDesc object used when fig is not None to specify the (row, col) of the subplot in the grid.
             exchange_xy: True to exchange the x and y in the plot.
             xfactor, yfactor: xvalues and yvalues are multiplied by this factor before plotting.
@@ -594,7 +594,7 @@ def plotly(self, exchange_xy=False, fig=None, rcd=None, **kwargs):
             rcd: PlotlyRowColDesc object used when fig is not None to specify the (row, col)
                 of the subplot in the grid.
 
-        Returns: |plotly-Figure|.
+        Returns: plotly-Figure
         """
         fig, _ = get_fig_plotly(fig=fig)
         rcd = PlotlyRowColDesc.from_object(rcd)

abipy/core/structure.py

@@ -1617,7 +1617,7 @@ def plotly_bz(self, fig=None, pmg_path=True, with_labels=True, **kwargs):
             pmg_path (bool): True if the default path used in pymatgen should be show.
             with_labels (bool): True to plot k-point labels.
 
-        Returns: |plotly.graph_objects.Figure|
+        Returns: plotly.graph_objects.Figure
         """
         from abipy.tools.plotting import plotly_brillouin_zone_from_kpath, plotly_brillouin_zone
         labels = None if not with_labels else self.hsym_kpath.kpath["kpoints"]
@@ -2033,8 +2033,8 @@ def make_doped_supercells(self, scaling_matrix, replaced_atom, dopant_atom):
                 b. A sequence of three scaling factors. e.g., [2, 1, 1]
                    specifies that the supercell should have dimensions 2a x b x c.
                 c. A number, which simply scales all lattice vectors by the same factor.
-            replaced atom : Symbol of the atom to be replaced (ex: 'Sr')
-            dopant_atom : Symbol of the dopant_atom (ex: 'Eu')
+            replaced atom: Symbol of the atom to be replaced (ex: 'Sr')
+            dopant_atom: Symbol of the dopant_atom (ex: 'Eu')
         """
         ### list of positions of non-equivalent sites for the replaced atom. ###
         irred = self.spget_equivalent_atoms().eqmap # mapping from inequivalent sites to atoms sites

abipy/dfpt/ddb.py

@@ -2601,12 +2601,10 @@ def plotly(self, w_min=0, w_max=None, gamma_ev=1e-4, num=500, component='diag',
             num: number of values of the frequencies between w_min and w_max.
             component: determine which components of the tensor will be displayed. Can be a list/tuple of two
                 elements, indicating the indices [i, j] of the desired component or a string among::
-
                 * 'diag_av' to plot the average of the components on the diagonal
                 * 'diag' to plot the elements on diagonal
                 * 'all' to plot all the components in the upper triangle.
                 * 'offdiag' to plot the off-diagonal components in the upper triangle.
-
             reim: a string with "re" will plot the real part, with "im" selects the imaginary part.
             units: string specifying the units used for phonon frequencies. Possible values in
                 ("eV", "meV", "Ha", "cm-1", "Thz"). Case-insensitive.

abipy/dfpt/phonons.py

@@ -4386,7 +4386,7 @@ def combiplotly(self, qlabels=None, units='eV', ylims=None, width_ratios=(2, 1),
             width_ratios: Ratio between the width of the phonon bands plots and the DOS plots.
                 Used if plotter has DOSes.
             fontsize: fontsize for titles and legend.
-            linestyle_dict: Dictionary mapping labels to linestyle options passed to |plotly.graph_objects.scatter|.
+            linestyle_dict: Dictionary mapping labels to linestyle options passed to plotly.graph_objects.scatter.
 
         Returns: |plotly.graph_objects.Figure|
         """

abipy/electrons/ebands.py

@@ -3088,11 +3088,10 @@ def get_ifermi_fs(self, interpolation_factor=8, mu=0.0, eref="fermie", wigner_se
 
         Returns:
 
-        .. example::
+        example::
 
             r = ebands.get_ifermi_fs()
             r.fs_plotter.get_plot(plot_type="plotly").show()
-
         """
         r = self.get_ifermi_dense_bs(interpolation_factor, with_velocities)
 

abipy/electrons/psps.py

@@ -666,19 +666,17 @@ def read_coresd(self, rmax=None) -> tuple[np.ndarray, np.ndarray]:
     def read_tcorespl(self) -> tuple[np.ndarray, np.ndarray]:
         """
         Returns:
-            qmesh: Linear q-mesh in q-space
-            tcorespl: numpy array of shape [ntypat, 2, mqgrid_vl]
-                with the pseudo core density in reciprocal space on a regular grid.
-                Only if pseudo has_tcore
+            qmesh: Linear q-mesh in q-space.
+            tcorespl: array of shape [ntypat, 2, mqgrid_vl] with the pseudo core density in reciprocal space on a regular grid.
+            Only if pseudo has_tcore
         """
         return self.read_value("qgrid_vl"), self.read_value("nc_tcorespl")
 
     def read_vlspl(self) -> tuple[np.ndarray, np.ndarray]:
         """
         Returns:
             qmesh: Linear q-mesh in G-space
-            vlspl: numpy array of shape [ntypat, two, mqgrid_vl]
-                with the local part of each type of psp in q-space
+            vlspl: numpy array of shape [ntypat, two, mqgrid_vl] with the local part of each type of psp in q-space
         """
         return self.read_value("qgrid_vl"), self.read_value("vlspl")
 

abipy/scripts/oncv.py

@@ -278,9 +278,9 @@ def build():
     return pn.serve(build, **serve_kwargs)
 
 
-def main():
 
-    def str_examples():
+
+def get_epilog() -> str:
         return """\
 Usage example:
 
@@ -295,11 +295,8 @@ def str_examples():
     oncv.py notebook H.out             ==> Generate jupyter notebook to plot oncvpsp results.
 """
 
-    def show_examples_and_exit(err_msg=None, error_code=1):
-        """Display the usage of the script."""
-        sys.stderr.write(str_examples())
-        if err_msg: sys.stderr.write("Fatal Error\n" + err_msg + "\n")
-        sys.exit(error_code)
+
+def get_parser(with_epilog=False):
 
     def get_copts_parser(multi=False):
         # Parent parser implementing common options.
@@ -324,7 +321,7 @@ def get_copts_parser(multi=False):
     cli.add_expose_options_to_parser(plot_parser)
 
     # Build the main parser.
-    parser = argparse.ArgumentParser(epilog=str_examples(), formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser = argparse.ArgumentParser(epilog=get_epilog(), formatter_class=argparse.RawDescriptionHelpFormatter)
     from abipy.core.release import __version__
     parser.add_argument('-V', '--version', action='version', version=__version__)
 
@@ -379,6 +376,19 @@ def get_copts_parser(multi=False):
     #                    help="List of cutoff radii for vloc in Bohr.")
     #cli.add_expose_options_to_parser(p_hints)
 
+    return parser
+
+
+def main():
+
+    def show_examples_and_exit(err_msg=None, error_code=1):
+        """Display the usage of the script."""
+        sys.stderr.write(get_epilog())
+        if err_msg: sys.stderr.write("Fatal Error\n" + err_msg + "\n")
+        sys.exit(error_code)
+
+    parser = get_parser(with_epilog=True)
+
     # Parse command line.
     try:
         options = parser.parse_args()
@@ -396,5 +406,6 @@ def get_copts_parser(multi=False):
     # Dispatch
     return globals()["oncv_" + options.command](options)
 
+
 if __name__ == "__main__":
     sys.exit(main())

abipy/tools/plotting.py

@@ -1929,46 +1929,44 @@ def wrapper(*args, **kwargs):
         return fig
 
     # Add docstring to the decorated method.
-    s = (
-            "\n\n"
-            + """\
-                Keyword arguments controlling the display of the figure:
-                ================  ====================================================================
-                kwargs            Meaning
-                ================  ====================================================================
-                title             Title of the plot (Default: None).
-                show              True to show the figure (default: True).
-                hovermode         True to show the hover info (default: False)
-                savefig           "abc.png" , "abc.jpeg" or "abc.webp" to save the figure to a file.
-                write_json        Write plotly figure to `write_json` JSON file.
-                                  Inside jupyter-lab, one can right-click the `write_json` file from
-                                  the file menu and open with "Plotly Editor".
-                                  Make some changes to the figure, then use the file menu to save
-                                  the customized plotly plot.
-                                  Requires `jupyter labextension install jupyterlab-chart-editor`.
-                                  See https://github.com/plotly/jupyterlab-chart-editor
-                renderer          (str or None (default None)) –
-                                  A string containing the names of one or more registered renderers
-                                  (separated by ‘+’ characters) or None. If None, then the default
-                                  renderers specified in plotly.io.renderers.default are used.
-                                  See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html
-                config (dict)     A dict of parameters to configure the figure. The defaults are set in plotly.js.
-                chart_studio      True to push figure to chart_studio server. Requires authenticatios.
-                                  Default: False.
-                template          Plotly template. See https://plotly.com/python/templates/
-                                  ["plotly", "plotly_white", "plotly_dark", "ggplot2",
-                                   "seaborn", "simple_white", "none"]
-                                  Default is None that is the default template is used.
-                ================  ====================================================================
-        """
-    )
+    doc_str = """\n\n
+        Keyword arguments controlling the display of the figure:
+        ================  ====================================================================
+        kwargs            Meaning
+        ================  ====================================================================
+        title             Title of the plot (Default: None).
+        show              True to show the figure (default: True).
+        hovermode         True to show the hover info (default: False)
+        savefig           "abc.png" , "abc.jpeg" or "abc.webp" to save the figure to a file.
+        write_json        Write plotly figure to `write_json` JSON file.
+                          Inside jupyter-lab, one can right-click the `write_json` file from
+                          the file menu and open with "Plotly Editor".
+                          Make some changes to the figure, then use the file menu to save
+                          the customized plotly plot.
+                          Requires `jupyter labextension install jupyterlab-chart-editor`.
+                          See https://github.com/plotly/jupyterlab-chart-editor
+        renderer          (str or None (default None)) –
+                          A string containing the names of one or more registered renderers
+                          (separated by ‘+’ characters) or None. If None, then the default
+                          renderers specified in plotly.io.renderers.default are used.
+                          See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html
+        config (dict)     A dict of parameters to configure the figure. The defaults are set in plotly.js.
+        chart_studio      True to push figure to chart_studio server. Requires authenticatios.
+                          Default: False.
+        template          Plotly template. See https://plotly.com/python/templates/
+                          ["plotly", "plotly_white", "plotly_dark", "ggplot2",
+                           "seaborn", "simple_white", "none"]
+                          Default is None that is the default template is used.
+        ================  ====================================================================
+
+"""
 
     if wrapper.__doc__ is not None:
         # Add s at the end of the docstring.
-        wrapper.__doc__ += "\n" + s
+        wrapper.__doc__ += f"\n{doc_str}"
     else:
         # Use s
-        wrapper.__doc__ = s
+        wrapper.__doc__ = doc_str
 
     return wrapper
 

docs/Makefile

@@ -2,9 +2,10 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -j6
-#SPHINXOPTS   = 
-SPHINXBUILD   = sphinx-build
+#SPHINXOPTS    = -j6
+SPHINXOPTS   = 
+#SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = sphinx-build -v
 PAPER         =
 BUILDDIR      = _build
 
@@ -49,6 +50,7 @@ clean:
 html:
 	./generate_rst_files.py
 	rm -rf ../abipy/examples/flows/flow_*
+	export READTHEDOCS=1
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

docs/api/embedding_api.rst

@@ -1,19 +1,19 @@
 embedding Package
-============
+=================
 
 .. contents::
    :backlinks: top
 
 :mod:`embedding` Package
-----------------------
+------------------------
 
 .. automodule:: abipy.embedding
    :members:
    :undoc-members:
    :show-inheritance:
 
 :mod:`embedding_ifc` Module
-----------------------
+---------------------------
 
 .. automodule:: abipy.embedding.embedding_ifc
    :members:

docs/api/lumi_api.rst

@@ -5,7 +5,7 @@ lumi Package
    :backlinks: top
 
 :mod:`lumi` Package
-----------------------
+-------------------
 
 .. automodule:: abipy.lumi
    :members:

docs/api/ppcodes_api.rst

@@ -5,7 +5,7 @@ ppcodes Package
    :backlinks: top
 
 :mod:`ppcodes` Package
--------------------
+----------------------
 
 .. automodule:: abipy.ppcodes
    :members: