Merge pull request #15 from molssi-seamm/dev

Bug fixes and revamping the documentation

.github/workflows/CodeQL.yaml

@@ -0,0 +1,13 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ "main" ]
+
+jobs:
+  codeql:
+    name: CodeQL
+    uses: molssi-seamm/devops/.github/workflows/CodeQL.yaml@main

HISTORY.rst

@@ -2,6 +2,14 @@
 History
 =======
 
+2023.1.23 (23 January 2023)
+---------------------------
+
+* Corrected bugs, including if no dispersion term requested
+* Added preliminary version of accelerated optimization using
+  MOPAC for Hessians, etc. May not fully work at the moment.
+* Updated documentation theme and structure to match new style.
+
 2022.11.18 -- Added total charge and multiplicity to Psi4 input
 
 2021.2.11 (11 February 2021)

Makefile

@@ -1,6 +1,7 @@
 MODULE := psi4_step
-.PHONY: help clean clean-build clean-pyc clean-test lint format typing test dependencies
-.PHONY: test-all coverage html docs servedocs release check-release dist install uninstall
+.PHONY: help clean clean-build clean-docs clean-pyc clean-test lint format typing test
+.PHONY: dependencies test-all coverage html docs servedocs release check-release
+.PHONY: dist install uninstall
 .DEFAULT_GOAL := help
 define BROWSER_PYSCRIPT
 import os, webbrowser, sys
@@ -67,12 +68,16 @@ coverage-html: ## check code coverage quickly with the default Python, showing a
 	pytest -v --cov=$(MODULE) --cov-report=html:htmlcov --cov-report term --color=yes tests/
 	$(BROWSER) htmlcov/index.html
 
-html: ## generate Sphinx HTML documentation, including API docs
-	rm -f docs/developer/$(MODULE).rst
-	rm -f docs/developer/modules.rst
-	sphinx-apidoc -o docs/developer $(MODULE)
+clean-docs: ## remove files associated with building the docs
+	rm -f docs/api/$(MODULE).rst
+	rm -f docs/api/modules.rst
 	$(MAKE) -C docs clean
+
+html: clean-docs ## generate Sphinx HTML documentation, including API docs
+	sphinx-apidoc -o docs/api $(MODULE)
 	$(MAKE) -C docs html
+	rm -f docs/api/$(MODULE).rst
+	rm -f docs/api/modules.rst
 
 docs: html ## Make the html docs and show in the browser
 	$(BROWSER) docs/_build/html/index.html

README.rst

@@ -14,8 +14,8 @@ SEAMM Psi4 Plug-in
    :target: https://codecov.io/gh/molssi-seamm/psi4_step
    :alt: Code Coverage
 
-.. image:: https://img.shields.io/lgtm/grade/python/g/molssi-seamm/psi4_step.svg?logo=lgtm&logoWidth=18
-   :target: https://lgtm.com/projects/g/molssi-seamm/psi4_step/context:python
+.. image:: https://github.com/molssi-seamm/psi4_step/workflows/CodeQL/badge.svg
+   :target: https://github.com/molssi-seamm/psi4_step/security/code-scanning
    :alt: Code Quality
 
 .. image:: https://github.com/molssi-seamm/psi4_step/workflows/Documentation/badge.svg

devtools/conda-envs/test_env.yaml

@@ -9,8 +9,11 @@ dependencies:
   - pip
 
   # Of the code
-  - seamm
+  - numpy
+  - optking
   - psutil
+  - scipy
+  - seamm
 
   # Testing
   - black
@@ -19,10 +22,11 @@ dependencies:
   - pytest
   - pytest-cov
 
-    # Pip-only installs
+  # Documentation
+  - pydata-sphinx-theme
+  - sphinx-design
+
+  # Pip-only installs
   - pip:
     # Documentation
-    - rinohtype
-    - pygments
-    - sphinx-rtd-theme
-    - pystemmer
+    - sphinx-copybutton

docs/_static/README.md

@@ -0,0 +1,16 @@
+# Static Doc Directory
+
+Add any paths that contain custom static files (such as style sheets) here,
+relative to the `conf.py` file's directory. 
+They are copied after the builtin static files,
+so a file named "default.css" will overwrite the builtin "default.css".
+
+The path to this folder is set in the Sphinx `conf.py` file in the line: 
+```python
+templates_path = ['_static']
+```
+
+## Examples of file to add to this directory
+* Custom Cascading Style Sheets
+* Custom JavaScript code
+* Static logo images

docs/_static/css/custom.css

@@ -1,24 +1,73 @@
-/* Make the page wider so e.g. the status table can be seen fully */
-.wy-nav-content {
-    max-width: 1200px !important;
+@import "../basic.css";
+
+html[data-theme="light"] {
+    --pst-color-primary: #ed1c24;
+	--pst-color-warning: #ed1c24;
+	--pst-color-primary-highlight: #bc151b;
+	--pst-color-secondary: #1d35e7;
+	--pst-color-secondary-highlight: #3e51e3;
+
+}
+
+html[data-theme="dark"] {
+    --pst-color-primary: #ed1c24;
+	--pst-color-warning: #ed1c24;
+	--pst-color-primary-highlight: #bc151b;
+	--pst-color-background: #1A1A1A;
+	--pst-color-secondary: #1d35e7;
+	--pst-color-secondary-highlight: #3e51e3;
+
+
+}
+
+html[data-theme="light"] a:hover {
+	color: #1A1A1A;
+}
+
+html[data-theme="dark"] h1, html[data-theme="dark"] h2, html[data-theme="dark"] h3, html[data-theme="dark"] h4, html[data-theme="dark"] h5, html[data-theme="dark"] h6 {
+	color: #ffffff;
+}
+
+
+html[data-theme="dark"] a {
+	color: #ffffff;
+}
+
+html[data-theme="dark"] .reference.external {
+	text-decoration: underline;
+
+}
+
+html[data-theme="dark"] p .reference.internal {
+	text-decoration: underline;
+
+}
+
+html[data-theme="dark"] a:hover {
+	color: #ed1c24;
+}
+
+html[data-theme="dark"] .prev-next-area a p.prev-next-title {
+    color: white;
 }
-.column_left {
-  display: table-cell;
-  width: 60px;
-  vertical-align: middle;
+
+html[data-theme="dark"] .prev-next-area:hover a:hover p.prev-next-title:hover {
+    color: #ed1c24;
 }
-.column {
-  display: table-cell;
+
+html[data-theme="dark"] dt:target {
+    background-color: #000000;
 }
-.column_right {
-  display: table-cell;
-  width: 60px;
-  vertical-align: middle;
+
+html .toctree-wrapper li[class^=toctree-l] {
+	list-style: circle;
 }
 
-/* Clear floats after the columns */
-.row:after {
-  content: "";
-  display: table;
-  clear: both;
+img:not(.logo__image, .footer_logo) {
+	padding: 20px;
+}
+
+
+.footer_logo {
+	max-height: 60px;
 }

docs/_templates/README.md

@@ -0,0 +1,14 @@
+# Templates Doc Directory
+
+Add any paths that contain templates here, relative to  
+the `conf.py` file's directory.
+They are copied after the builtin template files,
+so a file named "page.html" will overwrite the builtin "page.html".
+
+The path to this folder is set in the Sphinx `conf.py` file in the line: 
+```python
+html_static_path = ['_templates']
+```
+
+## Examples of file to add to this directory
+* HTML extensions of stock pages like `page.html` or `layout.html`

docs/_templates/molssi_footer.html

@@ -0,0 +1,44 @@
+{% if not theme_logo.get("link") %}
+  {% set href = pathto(root_doc) %}
+{% elif hasdoc(theme_logo.get("link")) %}
+  {% set href = pathto(theme_logo.get("link")) %} {# internal page #}
+{% else %}
+  {% set href = theme_logo.get("link") %} {# external url #}
+{% endif %}
+
+{# get all the brand information from html_theme_option #}
+  {% set is_logo = logo or theme_logo.get("image_light") or theme_logo.get("image_dark") %}
+  {% set image_light = theme_logo.get("molssi_light") or logo %}
+  {% set image_dark = theme_logo.get("molssi_dark") or logo %}
+  {% set image_light = image_light if image_light.startswith("http") else pathto('_static/' + image_light, 1) %}
+  {% set image_dark = image_dark if image_dark.startswith("http") else pathto('_static/' + image_dark, 1) %}
+  {% set alt = theme_logo.get("alt_text", "Logo image") %}
+  {% set nsf_logo = pathto('_static/' + 'nsf.png', 1)  %}
+
+
+<div class="row h-10">
+    <div class="col-2">
+        <a href="https://molssi.org/" target="_blank" title="Go to MolSSI in a new tab">
+            <img src="{{ image_light }}" class="logo__image only-light footer_logo" alt="{{ alt }}">
+            <img src="{{ image_dark }}" class="logo__image only-dark footer_logo" alt="{{ alt }}">
+        </a>
+    </div>
+    <div class="col-8">
+        <p> &copy; Copyright 2019-2023 <a href="https://molssi.org/">The Molecular Sciences Software Institute</a></p>
+        <p>Funded by the National Science Foundation 
+          <a href="https://nsf.gov/awardsearch/showAward?AWD_ID=1547580">OAC-1547580</a> and 
+          <a href="https://www.nsf.gov/awardsearch/showAward?AWD_ID=2136142">CHE-2136142.</a></p>
+
+        {% if show_sphinx %}
+        <p class="sphinx-version">
+        {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}<br>
+        </p>
+        {% endif %}
+
+    </div>
+    <div class="col-2">
+        <a href="https://nsf.gov/" target="_blank" title="Go to the NSF in a new tab">
+            <img src="{{ nsf_logo }}" class="footer_logo" alt="The NSF">
+          </a>
+    </div>
+</div>

docs/user/index.rst → docs/api/index.rst

@@ -1,15 +1,17 @@
-User Documentation
-==================
+API Documentation
+=================
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
-   overview
+   modules
+
 
 Indices and tables
 ------------------
 
 * :ref:`genindex`
+* :ref:`modindex`
 * :ref:`search`

docs/conf.py

@@ -44,7 +44,9 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.githubpages',
     'sphinx.ext.napoleon',
-    'sphinx.ext.viewcode'
+    'sphinx.ext.viewcode',
+    'sphinx_design',
+    'sphinx_copybutton'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -61,7 +63,7 @@
 
 # General information about the project.
 project = u'SEAMM Psi4 Plug-in'
-copyright = u"2020-2021, Molecular Sciences Software Institute (MolSSI)"
+copyright = u"2020-2023, Molecular Sciences Software Institute (MolSSI)"
 
 # The version info for the project you're documenting, acts as replacement
 # for |version| and |release|, also used in various other places throughout
@@ -102,7 +104,7 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'default'
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -116,12 +118,31 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+html_theme = "pydata_sphinx_theme"
 
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the
 # documentation.
 # html_theme_options = {}
+html_theme_options = {
+    "github_url": "https://github.com/molssi-seamm/geometry_analysis_step",
+    "twitter_url": "https://twitter.com/MolSSI_NSF",
+    "logo": {
+        "image_light": "SEAMM logo.png",
+        "image_dark": "SEAMM inverted.png",
+        "text": "Psi4",
+        "molssi_light": "molssi_main_logo.png",
+        "molssi_dark": "molssi_main_logo_inverted_white.png",
+    },
+    "show_toc_level": 2,
+    "header_links_before_dropdown": 4,
+    "external_links": [
+        {"name": "SEAMM Documentation", "url": "https://molssi-seamm.github.io"},
+        {"name": "MolSSI", "url": "https://molssi.org"}
+    ],
+    "secondary_sidebar_items": ["page-toc", "sourcelink"],
+    "footer_items": [ "molssi_footer" ],
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

docs/developer/index.rst → docs/developer_guide/index.rst

@@ -8,12 +8,4 @@ Contents:
 
    installation
    usage
-   modules
    contributing
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`