Unify docs workflows (#646)

* Unify docs workflows

* Fix poetry install

* Oops, missed a spot

* Reverting back

* [pre-commit.ci] Add auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Small fix

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.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 }}

.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

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

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"]