diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b5157bef1..208619849 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -43,27 +43,73 @@ jobs: - uses: actions/checkout@v4.1.7 with: submodules: 'true' - - name: Install dependencies, run unit tests and coverage report + - name: Install poetry run: python3 -m pip install --upgrade pip && python3 -m pip install poetry - - name: Set up Python - uses: actions/setup-python@v5.1.0 + - uses: actions/setup-python@v5.1.0 with: python-version: '3.10' cache: 'poetry' - name: Install dependencies, build docs without running notebooks run: | python3 -m pip install --upgrade pip && python3 -m pip install poetry + poetry env use '3.10' + source $(poetry env info --path)/bin/activate + poetry install --with docs,test --all-extras # Install Pandoc PANDOC_VERSION="2.19" curl -sLo- "https://github.com/jgm/pandoc/releases/download/${PANDOC_VERSION}/pandoc-${PANDOC_VERSION}-linux-amd64.tar.gz" | tar xzf - --strip-components 2 -C /usr/local/bin --exclude="share" + cd docs + rm -rf source/reference/api/_autosummary + make html + - name: Set up Node.js + uses: actions/setup-node@v4.0.2 + with: + node-version: 18 + cache: yarn + cache-dependency-path: '**/yarn.lock' + - name: Build webpage + run: | + cd docs/cyclops-webpage + yarn install --frozen-lockfile + yarn build + cp -r ../build/html build/api + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v4.0.0 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_branch: github_pages + publish_dir: docs/cyclops-webpage/build + + release-build: + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + needs: build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4.1.7 + with: + submodules: 'true' + - name: Install poetry + run: python3 -m pip install --upgrade pip && python3 -m pip install poetry + - uses: actions/setup-python@v5.1.0 + with: + python-version: '3.10' + cache: 'poetry' + - name: Install dependencies, build docs with notebook execution + run: | + python3 -m pip install --upgrade pip && python3 -m pip install poetry poetry env use '3.10' source $(poetry env info --path)/bin/activate poetry install --with docs,test --all-extras + + # Install Pandoc + PANDOC_VERSION="2.19" + curl -sLo- "https://github.com/jgm/pandoc/releases/download/${PANDOC_VERSION}/pandoc-${PANDOC_VERSION}-linux-amd64.tar.gz" | tar xzf - --strip-components 2 -C /usr/local/bin --exclude="share" + cd docs rm -rf source/reference/api/_autosummary - make html SPHINXOPTS="-D nbsphinx_execute='never'" + make html-with-notebooks - name: Set up Node.js uses: actions/setup-node@v4.0.2 with: @@ -77,7 +123,6 @@ jobs: yarn build cp -r ../build/html build/api - name: Deploy to GitHub Pages - if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged == true) uses: peaceiris/actions-gh-pages@v4.0.0 with: github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/docs_release.yml b/.github/workflows/docs_release.yml deleted file mode 100644 index c045a52cc..000000000 --- a/.github/workflows/docs_release.yml +++ /dev/null @@ -1,69 +0,0 @@ -name: docs release - -on: - pull_request: - branches: - - main - paths: - - .pre-commit-config.yaml - - .github/workflows/docs_release.yml - - '**.py' - - '**.ipynb' - - '**.html' - - '**.jinja' - - '**.js' - - poetry.lock - - pyproject.toml - - '**.rst' - - '**.md' - - docs/cyclops-webpage - types: [labeled, closed] - -jobs: - build: - if: contains(github.event.pull_request.labels.*.name, 'release') || (github.event.action == 'closed' && github.event.pull_request.merged == true) - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4.1.7 - with: - submodules: 'true' - - name: Install dependencies, run unit tests and coverage report - run: python3 -m pip install --upgrade pip && python3 -m pip install poetry - - name: Set up Python - uses: actions/setup-python@v5.1.0 - with: - python-version: '3.10' - cache: 'poetry' - - name: Install dependencies, build docs with notebooks - run: | - python3 -m pip install --upgrade pip && python3 -m pip install poetry - - # Install Pandoc - PANDOC_VERSION="2.19" - curl -sLo- "https://github.com/jgm/pandoc/releases/download/${PANDOC_VERSION}/pandoc-${PANDOC_VERSION}-linux-amd64.tar.gz" | tar xzf - --strip-components 2 -C /usr/local/bin --exclude="share" - - poetry env use '3.10' - source $(poetry env info --path)/bin/activate - poetry install --with docs,test --all-extras - cd docs - rm -rf source/reference/api/_autosummary - make html - - name: Set up Node.js - uses: actions/setup-node@v4.0.2 - with: - node-version: 18 - cache: yarn - cache-dependency-path: '**/yarn.lock' - - name: Build webpage - run: | - cd docs/cyclops-webpage - yarn install --frozen-lockfile - yarn build - cp -r ../build/html build/api - - name: Deploy to GitHub Pages - if: github.event.action == 'closed' && github.event.pull_request.merged == true - uses: peaceiris/actions-gh-pages@v4.0.0 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_branch: github_pages - publish_dir: docs/cyclops-webpage/build diff --git a/.github/workflows/integration_tests.yml b/.github/workflows/integration_tests.yml index cf1ccef14..cbd360cc1 100644 --- a/.github/workflows/integration_tests.yml +++ b/.github/workflows/integration_tests.yml @@ -46,6 +46,7 @@ jobs: - uses: actions/setup-python@v5.1.0 with: python-version: '3.10' + cache: 'poetry' - name: Install dependencies and check code run: | export PATH=/opt/openmpi-4.1.5/bin:$PATH diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf10..54df55c00 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,19 +1,26 @@ # Minimal makefile for Sphinx documentation -# -# You can set these variables from the command line, and also -# from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build SOURCEDIR = source BUILDDIR = build -# Put it first so that "make" without argument is like "make help". +# Add this line to set a default value for INCLUDE_NOTEBOOKS +INCLUDE_NOTEBOOKS ?= 0 + help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) .PHONY: help Makefile +# Modified html target +html: + @INCLUDE_NOTEBOOKS=$(INCLUDE_NOTEBOOKS) $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +# New target for building with notebooks +html-with-notebooks: + @$(MAKE) html INCLUDE_NOTEBOOKS=1 + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile diff --git a/docs/source/conf.py b/docs/source/conf.py index f0fd64853..5977bcd39 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,6 +18,7 @@ sys.path.insert(0, os.path.abspath("../../cyclops")) +include_notebooks = os.environ.get("INCLUDE_NOTEBOOKS", "0") == "1" # -- Project information ----------------------------------------------------- @@ -47,9 +48,15 @@ "myst_parser", "sphinx_design", "sphinx_copybutton", - "nbsphinx", "IPython.sphinxext.ipython_console_highlighting", ] +exclude_patterns = ["**.ipynb_checkpoints"] +# Modify your extensions list +if include_notebooks: + extensions.append("nbsphinx") +else: + # When not including notebooks, add them to exclude_patterns + exclude_patterns.append("**.ipynb") autosummary_generate = True napoleon_google_docstring = False napoleon_numpy_docstring = True @@ -79,7 +86,6 @@ # 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 = ["**.ipynb_checkpoints"] source_suffix = [".rst", ".md"]