From e35ceae6aede18447467a6c761f4e43e18935c56 Mon Sep 17 00:00:00 2001 From: "Lea J. Haeusel" Date: Mon, 30 Dec 2024 18:36:00 +0100 Subject: [PATCH] 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 --- .../create_python_environment/action.yml | 24 +++++++++ .github/workflows/documentation.yml | 50 +++++++++++++++++++ .../{.github-ci.yml => tests_local.yml} | 30 +++++------ doc/source/conf.py | 22 ++++---- doc/source/index.rst | 2 +- 5 files changed, 103 insertions(+), 25 deletions(-) create mode 100644 .github/actions/create_python_environment/action.yml create mode 100644 .github/workflows/documentation.yml rename .github/workflows/{.github-ci.yml => tests_local.yml} (68%) diff --git a/.github/actions/create_python_environment/action.yml b/.github/actions/create_python_environment/action.yml new file mode 100644 index 00000000..dd28ba39 --- /dev/null +++ b/.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 diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 00000000..f22d7804 --- /dev/null +++ b/.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 diff --git a/.github/workflows/.github-ci.yml b/.github/workflows/tests_local.yml similarity index 68% rename from .github/workflows/.github-ci.yml rename to .github/workflows/tests_local.yml index 47c761a2..50ef55d8 100644 --- a/.github/workflows/.github-ci.yml +++ b/.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 diff --git a/doc/source/conf.py b/doc/source/conf.py index 0e55b044..de532a85 100644 --- a/doc/source/conf.py +++ b/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.", diff --git a/doc/source/index.rst b/doc/source/index.rst index f47b5ace..4a59291c 100644 --- a/doc/source/index.rst +++ b/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::