diff --git a/.github/workflows/ci-build.yml b/.github/workflows/ci-build.yml index 8883275af..dc35c6b88 100644 --- a/.github/workflows/ci-build.yml +++ b/.github/workflows/ci-build.yml @@ -1,4 +1,4 @@ -name: Documentation Build +name: CI on: pull_request: @@ -8,70 +8,62 @@ on: branches: - main +env: + MAIN_PYTHON_VERSION: '3.10' + jobs: - pre-commit: - name: Pre-commit checks - runs-on: ubuntu-latest + style: + name: Code style + runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - - name: Setup Python + - name: Set up Python uses: actions/setup-python@v2 with: - python-version: '3.10' - - name: Install pre-commit requirements + python-version: ${{ env.MAIN_PYTHON_VERSION }} + - name: Install dependencies run: | - pip install pre-commit~=2.16.0 + python -m pip install --upgrade pip tox + - name: Test with tox + run: tox -e style - - name: Run pre-commit - run: | - pre-commit run --all-files || ( git status --short ; git diff ; exit 1 ) - - docs_build: + docs: + name: Documentation runs-on: ubuntu-latest - steps: - uses: actions/checkout@v2 - - name: Setup Python - uses: actions/setup-python@v2.2.2 + - name: Set up Python + uses: actions/setup-python@v2 with: - python-version: 3.8 + python-version: ${{ env.MAIN_PYTHON_VERSION }} - - name: Install diagrams dependencies + - name: Install system dependencies run: | sudo apt-get update - sudo apt-get install nodejs npm graphviz + sudo apt-get install -y texlive-latex-extra latexmk nodejs npm graphviz npm install -g @mermaid-js/mermaid-cli - - name: Build HTML Documentation + - name: Install Python dependencies run: | - pip install -r requirements_docs.txt --disable-pip-version-check - make -C doc html SPHINXOPTS="-W" - touch doc/build/html/.nojekyll - echo "dev.docs.pyansys.com" > doc/build/html/CNAME - - - name: Deploy to gh-pages on main - if: github.ref == 'refs/heads/main' - uses: JamesIves/github-pages-deploy-action@4.1.5 - with: - token: ${{ secrets.github_token }} - branch: gh-pages - folder: doc/build/html - clean: true - single-commit: true - + python -m pip install --upgrade pip tox + + - name: Build HTML documentation + run: tox -e doc + - name: Build PDF Documentation run: | sudo apt update sudo apt-get install -y texlive-latex-extra latexmk + python -m pip install -r requirements/requirements_doc.txt make -C doc latexpdf - - name: Upload HTML Documentation + - name: Upload HTML documentation uses: actions/upload-artifact@v2.2.4 with: name: HTML-Documentation - path: doc/build/html + path: .tox/doc_out_html/ retention-days: 7 - name: Upload PDF Documentation @@ -81,9 +73,19 @@ jobs: path: doc/build/latex/*.pdf retention-days: 7 - Release: + - name: Deploy to gh-pages + if: github.event_name == 'push' && contains(github.ref, 'refs/tags') + uses: JamesIves/github-pages-deploy-action@3.7.1 + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + BRANCH: gh-pages + FOLDER: .tox/doc_out_html/ + CLEAN: true + SINGLE_COMMIT: true + + release: if: github.event_name == 'push' && contains(github.ref, 'refs/tags') - needs: docs_build + needs: [style, docs] runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 @@ -91,7 +93,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v1 with: - python-version: 3.8 + python-version: ${{ env.MAIN_PYTHON_VERSION }} - uses: actions/download-artifact@v2 diff --git a/.github/workflows/nightly-build.yml b/.github/workflows/nightly-build.yml index 4c190bc04..218dc2074 100644 --- a/.github/workflows/nightly-build.yml +++ b/.github/workflows/nightly-build.yml @@ -1,47 +1,50 @@ name: Nightly Documentation Build - on: schedule: # UTC at 0400 - cron: '0 4 * * */2' # To run every 3 days workflow_dispatch: +env: + MAIN_PYTHON_VERSION: '3.10' + jobs: - nightly_docs_build: + nightly-docs: + name: Nightly documentation runs-on: ubuntu-latest - steps: - uses: actions/checkout@v2 - - name: Setup Python - uses: actions/setup-python@v2.2.2 + - name: Set up Python + uses: actions/setup-python@v2 with: - python-version: 3.8 + python-version: ${{ env.MAIN_PYTHON_VERSION }} - - name: Install mermaid-cli + - name: Install system dependencies run: | sudo apt-get update - sudo apt-get install nodejs npm graphviz + sudo apt-get install -y texlive-latex-extra latexmk nodejs npm graphviz npm install -g @mermaid-js/mermaid-cli - - name: Build HTML Documentation + - name: Install Python dependencies run: | - pip install -r requirements_docs.txt --disable-pip-version-check - make -C doc html SPHINXOPTS="-W" - touch doc/build/html/.nojekyll - echo "dev.docs.pyansys.com" > doc/build/html/CNAME - + python -m pip install --upgrade pip tox + + - name: Build HTML documentation + run: tox -e doc + - name: Build PDF Documentation run: | sudo apt update sudo apt-get install -y texlive-latex-extra latexmk + python -m pip install -r requirements/requirements_doc.txt make -C doc latexpdf - - name: Upload HTML Documentation + - name: Upload HTML documentation uses: actions/upload-artifact@v2.2.4 with: name: HTML-Documentation - path: doc/build/html + path: .tox/doc_out_html/ retention-days: 7 - name: Upload PDF Documentation @@ -52,10 +55,11 @@ jobs: retention-days: 7 - name: Deploy to gh-pages - uses: JamesIves/github-pages-deploy-action@4.1.5 + if: github.event_name == 'push' && contains(github.ref, 'refs/tags') + uses: JamesIves/github-pages-deploy-action@3.7.1 with: - token: ${{ secrets.github_token }} - branch: gh-pages - folder: doc/build/html - clean: true - single-commit: true + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + BRANCH: gh-pages + FOLDER: .tox/doc_out_html/ + CLEAN: true + SINGLE_COMMIT: true diff --git a/.gitignore b/.gitignore index 85bc252d6..a1b2a58e2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,21 +1,165 @@ -# Compiled source # -################### -*.pyc +# Created by https://www.toptal.com/developers/gitignore/api/python +# Edit at https://www.toptal.com/developers/gitignore?templates=python -# packages -dist/* +### Python ### +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class -# Pip generated folders # -######################### +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ *.egg-info/ +.installed.cfg +*.egg +MANIFEST -# Build docs and packages -build/* -doc/build/ -.vscode/ +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +doc/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock -# virtual environment +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintainted in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +.idea/ + +# Visual Studio +.vs/ +.vscode/ + +# End of https://www.toptal.com/developers/gitignore/api/python -# sphinx autogen +# Sphinx autogen doc/source/how-to/api/* diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 318a756a4..fbc07143d 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -26,8 +26,10 @@ repos: - id: check-merge-conflict - id: debug-statements -# this validates our github workflow files - repo: https://github.com/python-jsonschema/check-jsonschema - rev: 0.14.0 + rev: 0.16.0 hooks: - id: check-github-workflows + name: "Check GitHub workflows" + files: ^\.github/workflows/ + types: [yaml] diff --git a/configure_venv.bat b/configure_venv.bat deleted file mode 100644 index 580a4b349..000000000 --- a/configure_venv.bat +++ /dev/null @@ -1,6 +0,0 @@ -@echo off -setlocal - -python -m venv venv -pip install -r requirements_docs.txt -venv\Scripts\activate.bat diff --git a/configure_venv.sh b/configure_venv.sh deleted file mode 100644 index 44c236d8e..000000000 --- a/configure_venv.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/sh - -python -m venv venv -pip install -r requirements_docs.txt -venv/activate diff --git a/requirements_docs.txt b/requirements/requirements_doc.txt similarity index 81% rename from requirements_docs.txt rename to requirements/requirements_doc.txt index ee881d90b..7bc5e790f 100644 --- a/requirements_docs.txt +++ b/requirements/requirements_doc.txt @@ -1,5 +1,5 @@ Sphinx==4.5.0 -ansys-sphinx-theme>=0.4.0 +ansys-sphinx-theme==0.4.2 sphinx-copybutton==0.5.0 sphinx_toolbox==3.1.1 sphinx-tabs>=1.2.1,<3.4.0 diff --git a/tox.ini b/tox.ini new file mode 100644 index 000000000..657d3cb25 --- /dev/null +++ b/tox.ini @@ -0,0 +1,37 @@ +[tox] +description = Default environments to be executed when calling tox +envlist = + style + doc +isolated_build = true +isolated_build_env = build +skipsdist = true + +[testenv] +description = Generic environment configuration +basepython = + {style,doc,build}: python3 +passenv = * +setenv = + PYTHONUNBUFFERED = yes +skip_install = false + +[testenv:style] +description = Checks if code style applies +skip_install = true +deps = + pre-commit +commands = + pre-commit install + pre-commit run --all-files --show-diff-on-failure + +[testenv:doc] +description = Checks if project documentation properly builds +skip_install = false +deps = + -r{toxinidir}/requirements/requirements_doc.txt +allowlist_externals=* +commands = + sphinx-build -d "{toxworkdir}/doc_doctree" doc/source "{toxworkdir}/doc_out_html" --color -vW -b html + touch "{toxworkdir}/doc_out_html/.nojekyll" + bash -c 'echo "dev.docs.pyansys.com" > "{toxworkdir}/doc_out_html/CNAME"'