Add documentation structure (#37)

.github/workflows/website.yaml

@@ -1,52 +1,79 @@
 name: build_website
 
 on:
+
   push:
+
     branches:
       - master
 
 permissions:
+
   contents: write
   deployments: write
   pages: write
 
 jobs:
+
   build:
+
     runs-on: ubuntu-latest
 
     permissions:
+
       contents: write
       deployments: write
       pages: write
 
     steps:
-    - uses: actions/checkout@v3
 
-    - name: Install development and distributions version
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Install dependencies
       run: |
         pip install --upgrade pip
-        pip install .[doc]
         pip install pypandoc_binary
+        pip install .[doc]
 
     - name: Setup pandoc
       uses: siacodelabs/setup-pandoc@v1
       with:
-        xelatex: true.
+        xelatex: true
 
-    # didn't need to change anything here, but had to add sphinx.ext.githubpages
-    # to my conf.py extensions list. that fixes the broken uploads
-    - name: Building documentation
+    - name: Build documentation
       run: |
-        sphinx-apidoc -a -o ./docs/source/pyapi/ ./atomdb/ ./atomdb/test/ ./atomdb/data/ ./atomdb/datasets/ --separate
-        sphinx-build -M html docs/source _build 
-
-    # still need to build and set the PAT to get a rebuild on the pages job,
-    # apart from that quite clean and nice
-    - name: GitHub Pages Action
-      #if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-      uses: peaceiris/actions-gh-pages@v3
+        sphinx-apidoc -a -e -o docs/source/api atomdb
+        sphinx-build -M html docs/source build
+        touch build/html/.nojekyll
+
+    - name: Fix documentation permissions
+      run: |
+        chmod -c -R +rX "build/html/" | while read line; do
+          echo "::warning title=Invalid file permissions automatically fixed::$line"
+        done
+
+    - name: Upload Pages artifact
+      uses: actions/upload-pages-artifact@v3
       with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: _build/html
-        publish_branch: gh-pages
-        cname: atomdb.qcdevs.org
+        path: build/html/
+
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    needs: build
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{steps.deployment.outputs.page_url}}
+
+    steps:
+
+      - name: Deploy artifact to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -146,3 +146,6 @@ cython_debug/
 
 # Raw data files
 atomdb/datasets/*/raw/
+
+# Generated documentation
+docs/source/api/

docs/source/conf.py

@@ -1,123 +1,86 @@
-# Configuration file for the Sphinx documentation builder.
+import importlib
+import pathlib
+import sys
+
+#
+# Configure path
 #
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
+sys.path.insert(0, str(pathlib.Path(__file__).parents[2].absolute()))
 
-# 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 os
-import sys
+# Import module
+#
 
-sys.path.insert(0, os.path.abspath("."))
-sys.path.insert(0, os.path.abspath("../"))
+module = importlib.import_module("atomdb")
 
-# -- Project information -----------------------------------------------------
+#
+# Module info
+#
 
 project = "AtomDB"
-copyright = "2024, QC-Devs"
+
+project_copyright = "2024, QC-Devs"
+
 author = "QC-Devs"
 
+version = getattr(module, "version")
+
+release = version
 
-# -- General configuration ---------------------------------------------------
+#
+# General configuration
+#
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
-    "sphinx_rtd_theme",
     "sphinx.ext.autodoc",
+    "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.mathjax",
-    "nbsphinx",
-    "nbsphinx_link",
-    "IPython.sphinxext.ipython_console_highlighting"
+    "sphinx_rtd_theme",
 ]
 
-# List of arguments to be passed to the kernel that executes the notebooks:
-nbsphinx_execute_arguments = [
-    "--InlineBackend.figure_formats={'svg', 'pdf'}",
-    "--InlineBackend.rc=figure.dpi=200",
+templates_path = [
+    "_templates",
 ]
-# nbsphinx_input_prompt = 'In [%s]:'
-# nbsphinx_output_prompt = 'Out[%s]:'
-# explicitly dis-/enabling notebook execution
-nbsphinx_execute = "never"
-
-# Don't add .txt suffix to source files:
-html_sourcelink_suffix = ""
-
-# This is processed by Jinja2 and inserted before each notebook
-
-# nbsphinx_prolog = r"""
-# nbsphinx_epilog = r"""
-# {% set docname = env.docname.split("/")[-1] %}
-# .. raw:: html
-# .. role:: raw-html(raw)
-#  :format: html
-# .. nbinfo::
-#  The corresponding file can be obtained from:
-#  - Jupyter Notebook: :download:`{{docname+".ipynb"}}`
-#  - Interactive Jupyter Notebook: :raw-html:`<a href="https://mybinder.org/v2/gh/theochem/procrustes/master?filepath=doc%2Fnotebooks%2F/{{ docname }}.ipynb"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom"></a>`    """
-
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
 
+exclude_patterns = [
+    "_build",
+    "_themes/*",
+    "**.ipynb_checkpoints",
+    "Thumbs.db",
+    ".DS_Store",
+]
 
-# -- Options for HTML output -------------------------------------------------
+pygments_style = "sphinx"
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
-html_style = "css/override.css"
-
-# 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 = {"collapse_navigation": False}
-
+# Autodoc configuration
+#
 
-# -- Configuration for autodoc extensions ---------------------------------
+autoclass_content = "both"
+autodoc_member_order = "bysource"
 
 autodoc_default_options = {
+    "members": True,
     "undoc-members": True,
-    "show-inheritance": True,
-    "members": None,
     "inherited-members": True,
+    "show-inheritance": True,
     "ignore-module-all": True,
 }
 
+#
+# HTML configuration
+#
 
-add_module_names = False
-
-
-def autodoc_skip_member(app, what, name, obj, skip, options):
-    """Decide which parts to skip when building the API doc."""
-    if name == "__init__":
-        return False
-    if name.startswith("test_"):
-        return False
-    return skip
+html_show_sourcelink = False
+html_style = "css/override.css"
+html_theme = "sphinx_rtd_theme"
 
+html_theme_options = {
+    "collapse_navigation": False,
+}
 
-def setup(app):
-    """Set up sphinx."""
-    app.connect("autodoc-skip-member", autodoc_skip_member)
+html_static_path = [
+    "_static",
+]

docs/source/index.rst

@@ -3,22 +3,44 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to AtomDB's documentation!
-==================================
+|Python3| |GitHub|
+
+AtomDB
+======
+
+AtomDB is an extended database, or periodic table, of neutral and charged atomic
+properties.
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+    :maxdepth: 2
+    :caption: Introduction
+
+    intro/about
+    intro/license
+    intro/citing
+    intro/conduct
 
 .. toctree::
-   :maxdepth: 2
-   :caption: API Documentation
+    :maxdepth: 2
+    :caption: User Documentation
 
-   pyapi/modules.rst
+    user/install
+    user/tutorial
+
+.. toctree::
+    :maxdepth: 3
+    :caption: API Reference
+
+    api/modules
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+.. |Python3| image:: https://img.shields.io/badge/python%203-f0f0f0.svg?logo=Python
+   :target: https://docs.python.org/3/
+.. |GitHub| image:: https://img.shields.io/badge/theochem-000000.svg?logo=GitHub
+   :target: https://github.com/theochem/AtomDB/

docs/source/intro/about.rst

@@ -0,0 +1,2 @@
+About
+=====

docs/source/intro/citing.rst

@@ -0,0 +1,13 @@
+Citing AtomDB
+=============
+
+If you publish work resulting from the use of AtomDB, please cite us as follows:
+
+.. code:: bibtex
+
+    @misc{atomdb,
+      author = {S{\'a}nchez D{\'i}az, Gabriela and Richer, Michelle and Tehrani, Alireza and Bianchi, Julianna and Ayers, Paul W. and Heidar-Zadeh, Farnaz},
+      title  = {{AtomDB: A Python Library for Atomic and Promolecular Properties}},
+      year   = {2024},
+      url    = {https://atomdb.qcdevs.org/},
+    }

docs/source/intro/conduct.rst

@@ -0,0 +1,9 @@
+Code of Conduct
+===============
+
+We have zero tolerance for disrespectful or inconsiderate contributions, and
+contributors to AtomDB must adhere to the `QC-Devs Code of Conduct`__.
+
+.. _CodeOfConduct: https://qcdevs.org/guidelines/qcdevs_code_of_conduct/
+
+__ CodeOfConduct_

docs/source/intro/license.rst

@@ -0,0 +1,19 @@
+License
+=======
+
+AtomDB is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+AtomDB is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+* `GNU General Public License version 3`__
+
+.. _GPLv3: https://www.gnu.org/licenses/gpl-3.0
+
+__ GPLv3_
+
+