Update documentation

.github/workflows/docs.yml

@@ -23,7 +23,7 @@ jobs:
           pip install .[docs,featurizer]
       - name: Sphinx build
         run: |
-          sphinx-build docs/source _build
+          sphinx-build docs _build
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}

.github/workflows/python-package.yml

@@ -99,4 +99,4 @@ jobs:
           pip install .[docs,featurizer]
 
       - name: Build
-        run: sphinx-build docs/source docs_build
+        run: sphinx-build -W docs _build

CHANGELOG.md

@@ -1,3 +1,5 @@
+# Changelog
+=======
 ## v0.3.3
 - fixing which_bonds  by @JonasGrandel in https://github.com/JaGeo/LobsterPy/pull/168
 - fix create inputs alias not working; update test for the same by @naik-aakash in https://github.com/JaGeo/LobsterPy/pull/171

CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to LobsterPy
+
+We would love your input to further extend and improve our code. Contribution of any kind are welcome, for example it can be:
+
+- Reporting a bug
+- Discussing the current state of the code
+- Submitting a fix
+- Proposing or implementing new features
+- Or simply updating the documentation
+
+## Reporting bugs, getting help, and discussion
+
+You can submit questions and bugs to the
+[GitHub issues page](https://github.com/JaGeo/LobsterPy/issues).
+
+When creating a bug report, its best if you include some of the pointers mentioned below:
+
+- A quick summary and/or background.
+- Steps to reproduce - be specific! **Provide sample code.**
+- What was expected and what actually happened.
+- Screenshots of any errors you encounter.
+
+## Contributing code improvements or additions through Github
+
+- Fork the repo and create your branch from master.
+- If working using IDE, clone the repo and install the package in development mode `pip install -e lobsterpy[featurizer,dev,tests]` in a separate conda or virtual environment.
+- run `pre-commit install`  (This will install all the hooks from `.pre-commit-config.yaml` and make adapting your code to match linting standards)
+- Commit your improvements to your branch and push to your Github fork (repo).
+- Make sure you write tests and update documentation when needed. We use pytest framework and check out our existing tests for inspiration.
+- Try to reuse existing test data when possible.
+- When you're finished, go to your fork and make a Pull Request (PR). It will
+  automatically update if you need to make further changes.
+- If you have raised a PR but are actively working on it, please add `[WIP] in the title.(This will let us know it is still not ready for review or merged)

README.md

@@ -3,63 +3,85 @@
 # Getting started
 <img src="https://raw.githubusercontent.com/JaGeo/LobsterPy/main/LobsterPyLogo.png" alt="LobsterPy Logo which consists of a green Python and a red Lobster" width="200"/>
 
-This is a package that enables automatic plotting and summaries of Lobster outputs. You can download Lobster on [http://www.cohp.de](http://www.cohp.de). Currently, only VASP/Lobster computations are supported.
+LobsterPy is a package that enables automatic analysis of LOBTSER outputs to get summarized bonding information and relevant bond plots. Additionally, one can also generate features for machine learning studies from LOBSTER outputs. One can download LOBSTER from [http://www.cohp.de](http://www.cohp.de).
 
-Please note that LobsterPy relies on your Lobster outputs. Thus, please make sure that the outputs have enough information for our (automatic) analysis.
+<div style="border: 1px solid #52a5ab; padding: 5px; position: relative;">
+    <div style="background-color: #52a5ab; color: #ffffff; padding: 0px; position: absolute; top: 0; left: 0; right: 0; text-align: center;">
+        <strong>Important</strong>
+    </div>
+<br>
+
+Recently released [LOBSTER 5.0](https://schmeling.ac.rwth-aachen.de/cohp/index.php?menuID=6) now generates `POSCAR.lobster` for any kind of LOBSTER calculation by default (This file has same format as the POSCAR from VASP). Thus, LobsterPy in principle, now supports usage with **all** DFT codes supported by LOBSTER and is **no** longer limited to `VASP`. Almost all of the core functionalities of LobsterPy could be used. The user must use `POSCAR.lobster` for `path_to_poscar` and `-fstruct` argument in python and cli interface, respectively.
+
+The only functionality limited to VASP is DOS comparisons and basis set analysis in the `calc_quality_summary` method of the `Analysis` class, as it relies on VASP output files, namely `vasprun.xml` and `POTCAR`.
+</div>
+
+Please note that LobsterPy relies on the LOBSTER computation output files. Thus, it will be only able to analyze data that has been computed in the LOBSTER run.
 
 ![LobsterPyAnimation](https://github.com/JaGeo/LobsterPy/assets/22094846/8f06b84c-db6d-414c-8590-aa04c957c728)
 
 
 ## Installation
+### Standard installation
+Install using ``pip install lobsterpy``
 
-You can now use ``pip install lobsterpy`` to install it.
+### Installation with featurizer
+Install using ``pip install lobsterpy[featurizer]``
 
-You can also pip install the package in development mode by writing ``pip install -e .``. It will then use setup.py to install the package. One requirement of this package is [pymatgen](https://github.com/materialsproject/pymatgen).
 
 ## Basic usage
 
-* **Automatic analysis and plotting of COHPs:**
+* **Automatic analysis and plotting of COHPs / COBIS / COOPs:**
 
     <img src="https://github.com/JaGeo/LobsterPy/assets/22094846/6587e752-6ea4-4358-a763-3633d5a21869" alt="Output Automatic Analysis" width="300"/>
 
+You can use ``lobsterpy description`` for an automated analysis of COHPs for relevant cation-anion bonds or ``lobsterpy automatic-plot`` to plot the results automatically.
+It will evaluate all COHPs with ICOHP values down to 10% of the strongest ICOHP.
+You can enforce an analysis of all bonds by using ``lobsterpy automatic-plot --allbonds``.
+You can also switch the automatic analysis to use the ICOBIs or ICOOPs. You need to add `--cobis` or `--coops` along with the mentioned commands
+for e.g.like  ``lobsterpy description --cobis``
+
+An interactive plotter is available via ``lobsterpy automatic-plot-ia``.
+
+Currently, the computed Mulliken charges will be used to determine cations and anions. If no ``CHARGE.lobster`` is available, the algorithm will fall back to the BondValence analysis from pymatgen.
 
-    You can use ``lobsterpy description`` for an automated analysis of COHPs for relevant cation-anion bonds or ``lobsterpy automatic-plot`` to plot the results automatically. It will evaluate all COHPs with ICOHP values down to 10% of the strongest ICOHP. You can enforce an analysis of all bonds by using ``lobsterpy automatic-plot --allbonds`` . Currently, the computed Mulliken charges will be used to determine cations and anions. If no ``CHARGE.lobster`` is available, the algorithm will fall back to the BondValence analysis from pymatgen. Please be aware that LobsterPy can only analyze bonds that have been included in the initial Lobster computation. Thus, please use the cohpgenerator within Lobster. We have also added functionality to base the automatic analysis on the COBIs and COOPs.
+*Please be aware that LobsterPy can only analyze bonds that have been included in the initial Lobster computation. Thus, please use the cohpgenerator within Lobster.*
 
-    An interactive plotter is available via ``lobsterpy automatic-plot-ia``. And you can also plot densities of states from LOBSTER with ``lobsterpy plot-dos``.
 
-    It is also possible to start this automatic analysis from a Python script. See "examples" for scripts.
+It is also possible to start this automatic analysis from a Python script. See "examples" for scripts.
 
+* **Plotting DOS from LOBSTER computations:**
 
-* **Command line plotter**:
+  To plot densities of states obtained from LOBSTER use ``lobsterpy plot-dos``.
 
-    We included options to plot COHPs/COBIs/COOPs from the command line.
-    ``lobsterpy plot 1 2`` will plot COHPs of the first and second bond from ``COHPCAR.lobster``. It is possible to sum or integrate the COHPs as well (``--summed``, ``--integrated``). You can switch to COBIs or COOPs by using ``--cobis`` or ``--coops``, respectively.
+
+* **Generic COHP/ COOP / COBI plotter**:
+
+  We included options to plot COHPs/COBIs/COOPs from the command line.
+``lobsterpy plot 1 2`` will plot COHPs of the first and second bond from ``COHPCAR.lobster``. It is possible to sum or integrate the COHPs as well (``--summed``, ``--integrated``). You can switch to COBIs or COOPs by using ``--cobis`` or ``--coops``, respectively.
 
 * **Other command line tools**:
 
     ``lobsterpy create-inputs`` will create standard inputs based on existing POSCAR, POTCAR, INCAR files. It will allow to test for different basis sets that are available in Lobster. Currently only available for PBE_54 POTCARs.
 
 
-
 * **Further help?**
 
-    You can get further information by using ``lobsterpy --help`` and also by typing ``lobsterpy description --help``, ``lobsterpy automatic-plot --help``, ``lobsterpy plot --help``
+    You can get further information by using ``lobsterpy --help`` and also by typing ``lobsterpy description --help``,
+``lobsterpy automatic-plot --help``, ``lobsterpy plot --help``.
+
+## Comprehensive documentation
+* Checkout the [documentation and tutorials](https://jageo.github.io/LobsterPy/) for more details.
 
 ## How to cite?
 Please cite our paper: J. George, G. Petretto, A. Naik, M. Esters, A. J. Jackson, R. Nelson, R. Dronskowski, G.-M. Rignanese, G. Hautier, **ChemPlusChem**, [https://doi.org/10.1002/cplu.202200123](https://doi.org/10.1002/cplu.202200123).
 Please cite [pymatgen](https://github.com/materialsproject/pymatgen), [Lobster](https://www.cohp.de), and [ChemEnv](https://doi.org/10.1107/S2052520620007994) correctly as well.
 
-## LobsterPy as part of an atomate2 workflow
+## LobsterPy is now a part of an atomate2 workflow
 ![LobsterWorkflow](https://github.com/JaGeo/LobsterPy/assets/22094846/337615ac-542e-446c-bc63-fb5946b16544)
 
 We have now also included the automatic analysis into a fully automatic workflow using VASP and Lobster in [atomate2](https://github.com/materialsproject/atomate2). More documentation and information will follow soon.
 
-## Future plans:
-* Include orbitals into automatic plotting
-
-## Contributions
-* Contributions and suggestions for features are also welcome. Please write an Issue to describe your potential contribution or feature request.
-* We are planning to submit a paper for the code LobsterPy when more features have been added (~ mid of 2023). Major contributors will of course have the chance to be co-authors. Please talk to us if you are interested in contributing :).
 
 ## Acknowledgements
 The development of the program has been supported by a computing time grant. We gratefully acknowledge the Gauss Centre for Supercomputing e.V.(www.gauss-centre.eu) for funding this project by providing computing time on the GCS Supercomputer SuperMUC-NG at Leibniz Supercomputing Centre (www.lrz.de) (project pn73da).

docs/_static/custom.css

@@ -0,0 +1,128 @@
+/*******************************************************************************
+* light theme
+*
+* all the variables used for light theme coloring
+*/
+html[data-theme="light"] {
+  /*****************************************************************************
+  * main colors
+  */
+  --pst-color-primary: rgb(82, 165, 171);
+  --pst-color-secondary: rgb(200, 30, 109);
+  --pst-color-success: rgb(40, 167, 69);
+  --pst-color-info: var(--pst-color-primary);
+  --pst-color-warning: var(--pst-color-secondary);
+  --pst-color-danger: rgb(220, 53, 69);
+  --pst-color-text-base: rgb(51, 51, 51);
+  --pst-color-text-muted: rgb(77, 77, 77);
+  --pst-color-border: rgb(201, 201, 201);
+  --pst-color-shadow: rgb(216, 216, 216);
+
+  /*****************************************************************************
+  * depth colors
+  *
+  * background: the more in depth color
+  * on-background: the object directly set on the background, use of shadows in light theme
+  * surface: object set on the background (without shadows)
+  * on_surface: object set on surface object (without shadows)
+  */
+  --pst-color-background: rgb(255, 255, 255);
+  --pst-color-on-background: rgb(242, 239, 233);
+  --pst-color-surface: rgb(242, 239, 233);
+  --pst-color-on-surface: rgb(242, 239, 233);
+
+  /*****************************************************************************
+  * extentions
+  */
+
+  --pst-color-panel-background: var(--pst-color-background);
+
+  /*****************************************************************************
+  * layout
+  */
+
+  // links
+  --pst-color-link: var(--pst-color-primary);
+  --pst-color-link-hover: var(--pst-color-secondary);
+
+  // inline code
+  --pst-color-inline-code: rgb(232, 62, 140);
+
+  // targeted content
+  --pst-color-target: rgb(251, 229, 78);
+
+  // hide any content that should not be displayed in the light theme
+  .only-dark {
+    display: none !important;
+  }
+}
+
+/*******************************************************************************
+* dark theme
+*
+* all the variables used for dark theme coloring
+*/
+html[data-theme="dark"] {
+  /*****************************************************************************
+  * main colors
+  */
+  --pst-color-primary: rgb(82, 165, 171);
+  --pst-color-secondary: rgb(200, 30, 109);
+  --pst-color-success: rgb(72, 135, 87);
+  --pst-color-info: var(--pst-color-primary);
+  --pst-color-warning: var(--pst-color-secondary);
+  --pst-color-danger: rgb(203, 70, 83);
+  --pst-color-text-base: rgb(201, 209, 217);
+  --pst-color-text-muted: rgb(192, 192, 192);
+  --pst-color-border: rgb(192, 192, 192);
+  --pst-color-shadow: var(--pst-color-background);
+
+  /*****************************************************************************
+  * depth colors
+  *
+  * background: the more in depth color
+  * on-background: the object directly set on the background, use of a light grey in dark theme
+  * surface: object set on the background (without shadows)
+  * on_surface: object set on surface object (without shadows)
+  */
+  --pst-color-background: rgb(18, 18, 18);
+  --pst-color-on-background: rgb(30, 30, 30);
+  --pst-color-surface: rgb(41, 41, 41);
+  --pst-color-on-surface: rgb(55, 55, 55);
+
+  /*****************************************************************************
+  * extentions
+  */
+
+  --pst-color-panel-background: var(--pst-color-background-up);
+
+  /*****************************************************************************
+  * layout
+  */
+
+  // links
+  --pst-color-link: var(--pst-color-primary);
+  --pst-color-link-hover: var(--pst-color-secondary);
+
+  // inline code
+  --pst-color-inline-code: rgb(221, 158, 194);
+
+  // targeted content
+  --pst-color-target: rgb(71, 39, 0);
+
+  // hide any content that should not be displayed in the dark theme
+  .only-light {
+    display: none !important;
+  }
+
+  // specific brightness applied on images
+  img {
+    filter: brightness(0.8) contrast(1.2);
+  }
+}
+
+
+.bg-light {
+ background-color:rgba(80, 164, 171, 0.52)!important
+}
+

docs/_templates/autosummary/base.rst

@@ -0,0 +1,5 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/_templates/autosummary/class.rst

@@ -0,0 +1,7 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :show-inheritance:
+   :members:

docs/_templates/autosummary/function.rst

@@ -0,0 +1,5 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}

docs/_templates/autosummary/module.rst

@@ -0,0 +1,53 @@
+{% extends "!autosummary/module.rst" %}
+
+{# This file is almost the same as the default, but adds :toctree: and :nosignatures: to
+   the autosummary directives. The original can be found at
+   ``sphinx/ext/autosummary/templates/autosummary/module.rst``. #}
+
+{% block attributes %}
+{% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block functions %}
+{% if functions %}
+   .. rubric:: Functions
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block classes %}
+
+{% set types = [] %}
+{% for item in members %}
+   {% if not item.startswith('_') and not (item in functions or item in attributes or item in exceptions) %}
+      {% set _ = types.append(item) %}
+   {% endif %}
+{%- endfor %}
+
+{% if types %}
+   .. rubric:: Classes
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in types %}
+      {{ item }}
+   {%- endfor %}
+
+{% endif %}
+{% endblock %}

docs/about/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../../CHANGELOG.md
+```