Add workflow to build and deploy the documentation to github pages (#86)

* docs: add workflow to build and deploy the documentation to github pages

* docs: switch to deployment via action

* docs: update conf.py

* fix: Introduce action to create python environment

* fix: remove unnecessary env

.github/actions/create_python_environment/action.yml

@@ -0,0 +1,24 @@
+name: Create Python environment
+description: Create the QUEENS Python environment with all dependencies
+
+outputs:
+  ppm:
+    description: Python package manager
+    value: ${{ steps.environment.outputs.ppm }}
+
+runs:
+  using: composite
+  steps:
+    - uses: conda-incubator/setup-miniconda@v3
+    - name: Create environment and install QUEENS
+      id: environment
+      shell: bash -l {0}
+      env:
+        PYTHON_PACKAGE_MANAGER: conda
+      run: |
+        $PYTHON_PACKAGE_MANAGER env create -f environment.yml
+        $PYTHON_PACKAGE_MANAGER activate queens
+        pip install -e .[develop]
+        $PYTHON_PACKAGE_MANAGER env export > pipeline_conda_environment.yml
+        $PYTHON_PACKAGE_MANAGER list
+        echo "ppm=$PYTHON_PACKAGE_MANAGER" >> $GITHUB_OUTPUT

.github/workflows/documentation.yml

@@ -0,0 +1,50 @@
+# yamllint disable
+name: documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build-documentation:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create Python environment
+        id: environment
+        uses: ./.github/actions/create_python_environment
+      - name: Sphinx build
+        env:
+          PYTHON_PACKAGE_MANAGER: ${{steps.environment.outputs.ppm}}
+        run: |
+          $PYTHON_PACKAGE_MANAGER activate queens
+          sphinx-apidoc -o doc/source queens -f -M
+          cd doc
+          sphinx-build -b html -d build/doctrees source build/html
+      - name: Upload html
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: doc/build/html
+          retention-days: 1
+
+  deploy-documentation:
+    needs: build-documentation
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        if: ${{github.ref == 'refs/heads/main'}}
+        uses: actions/deploy-pages@v4

.github/workflows/.github-ci.yml → .github/workflows/tests_local.yml

@@ -1,13 +1,12 @@
 # yamllint disable
----
-#---------------------------------------------------------------------------------------------------
-env:
-  TEST_TIMING_OPTION: ""  # Set the option if local test should be timed or not. Default is off.
-  PYTHON_PACKAGE_MANAGER: "conda"  # Python package manager to create the python environments
-name: github_ci
+name: tests_local
 
 on: [pull_request]
 
+env:
+  # Set TEST_TIMING_OPTION if local test should be timed. Default is off.
+  TEST_TIMING_OPTION: ""
+
 jobs:
   run_tests:
     runs-on: ubuntu-latest
@@ -19,20 +18,21 @@ jobs:
         shell: bash -l {0}
     steps:
       - uses: actions/checkout@v4
-      - uses: conda-incubator/setup-miniconda@v3
-      - name: build
+      - name: Install rsync
         run: |
           sudo apt-get update
           sudo apt-get install -y rsync
+      - name: Create links to 4C
+        run: |
           ln -s /home/user/4C/build/4C config/4C
           ln -s /home/user/4C/build/post_ensight config/post_ensight
           ln -s /home/user/4C/build/post_processor config/post_processor
-          $PYTHON_PACKAGE_MANAGER env create -f environment.yml
-          $PYTHON_PACKAGE_MANAGER activate queens
-          pip install -e .[develop]
-          $PYTHON_PACKAGE_MANAGER env export > pipeline_conda_environment.yml
-          $PYTHON_PACKAGE_MANAGER list
-      - name: codechecks
+      - name: Create Python environment
+        id: environment
+        uses: ./.github/actions/create_python_environment
+      - name: Get Python package manager
+        run: echo "PYTHON_PACKAGE_MANAGER=${{steps.environment.outputs.ppm}}" >> $GITHUB_ENV
+      - name: Codechecks
         run: |
           $PYTHON_PACKAGE_MANAGER activate queens
           isort --check-only queens tests > track_isort.txt 2>&1
@@ -41,7 +41,7 @@ jobs:
           pylint queens tests --rcfile=.pylintrc --output-format=json:pylint_warnings.json --fail-under 0
           python .gitlab/pipeline_utils/code_quality_creator.py pylint_warnings.json
           pydocstyle --match-dir='^(?!.*test).*$' queens > track_pydocstyle.txt 2>&1
-      - name: tests
+      - name: Run pytest
         run: |
           $PYTHON_PACKAGE_MANAGER activate queens
           pytest -v -m "unit_tests or integration_tests or integration_tests_fourc" -o log_cli=true --log-cli-level=INFO --cov --cov-report=term --cov-report=html:html_coverage_report --cov-report=xml:xml_coverage_report.xml $TEST_TIMING_OPTION --color=yes --junitxml=test_junit.xml

doc/source/conf.py

@@ -81,9 +81,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "0.1"
+# version = "0.1"
 # The full version, including alpha/beta/rc tags.
-release = "0.1"
+# release = "0.1"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -104,7 +104,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["notebooks/firststeps.ipynb"]
+exclude_patterns = []
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -143,14 +143,18 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-# html_theme = 'alabaster'
 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 = {
+    "logo": {
+        "image_light": "https://raw.githubusercontent.com/queens-py/queens-design/main/logo/queens_logo_day.svg",
+        "image_dark": "https://raw.githubusercontent.com/queens-py/queens-design/main/logo/queens_logo_night.svg",
+    }
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -258,7 +262,7 @@
 # html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "pqueensdoc"
+htmlhelp_basename = "queensdoc"
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -281,7 +285,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (main_doc, "queens.tex", "queens Documentation", "Jonas Biehler", "manual"),
+    (main_doc, "queens.tex", "QUEENS Documentation", author, "manual"),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -321,7 +325,7 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(main_doc, "queens", "queens Documentation", [author], 1)]
+man_pages = [(main_doc, "queens", "QUEENS Documentation", [author], 1)]
 
 # If true, show URL addresses after external links.
 #
@@ -337,7 +341,7 @@
     (
         main_doc,
         "queens",
-        "queens Documentation",
+        "QUEENS Documentation",
         author,
         "queens",
         "One line description of project.",

doc/source/index.rst

@@ -3,7 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to QUEENS's documentation!
+Welcome to the QUEENS' documentation!
 ===================================
 
 .. toctree::