Optionally use make in build sphinx docs (#58)

* Use `make` in build sphinx docs

* Update documentation

* Add commadn to change dir before running `make` in README.md

* Make the use of `make` optional in `build_sphinx_docs`

* Update documentation

* Add `use-make` option in `deploy_sphinx_docs`

README.md

@@ -101,11 +101,14 @@ build_sphinx_docs:
     with:
       python-version: 3.10
       check-links: false
+      use-make: false
 ```
 The `python-version` input is optional and defaults to `3.x` (where `x` is the latest stable version of Python 3 available on the GitHub Actions platform)
 
 The `check-links` input is also optional and defaults to `true`. If set to `true`, the action will use the Sphinx linkcheck builder to check the integrity of all **external** links.
 
+The `use-make` input is optional and defaults to `false`. If set to `true`, the action will use the `make` utility with a custom `docs/Makefile` to build the pages from `SOURCEDIR` to `BUILDDIR` as defined in the Makefile. If set to `false`, the action will use `sphinx-build` to build the pages from `docs/source` to `docs/build`.
+
 ## Publish Sphinx documentation
 Deploys pre-built documentation to GitHub Pages.
 
@@ -122,7 +125,9 @@ deploy_sphinx_docs:
   - uses: neuroinformatics-unit/actions/deploy_sphinx_docs@main
     with:
       secret_input: ${{ secrets.GITHUB_TOKEN }}
+      use-make: false
 ```
+The `use-make` input is optional and defaults to `false`. If set to `true`, the action will assume that the Sphinx documentation is built using `make` and will use the `./docs/build/html` directory as the publish directory. If set to `false`, it will use the `./docs/build/` directory instead. 
 
 ## Full Workflows
 * An example workflow, including linting, testing and release can be found at [example_test_and_deploy.yml](./example_test_and_deploy.yml).

build_sphinx_docs/README.md

@@ -7,9 +7,11 @@ The various steps include:
   * the version can be specified via the `python-version` input, and defaults to `3.x`
 * installing pip and setting up pip cache
 * pip installing build dependencies (themes, build tools, etc.) from `docs/requirements.txt`
-* Checking that external links in the documentation are not broken 
+* checking that external links in the documentation are not broken 
   * optional, defaults to `true` (i.e. links are checked), see the [warning](#warning) below for more information
-* building the html pages from `docs/source` (should contain Sphinx source files) to `docs/build`
+* building the html pages in one of two ways, by setting the `use-make` input (default: `false`)
+  * (default) using `sphinx-build` to build the pages from `docs/source` (should contain Sphinx source files) to `docs/build`
+  * (`use-make: true`) using the `make` utility with a custom `docs/Makefile` to build the pages from `SOURCEDIR` to `BUILDDIR` as defined in the Makefile
 * uploading the built html pages as an artifact named `docs-build`, for use in other actions
 
 It can be run upon all pull requests, to ensure that documentation still builds.
@@ -22,6 +24,10 @@ You can debug the linkcheck step by running it locally:
 ```bash
 sphinx-build docs/source docs/build -b linkcheck
 ```
+or, if you have `docs/Makefile`:
+```bash
+cd docs && make linkcheck
+```
 If the linkcheck step produces "false positives" for your project (i.e. marking valid links as broken), you have two options:
 
 - Adding the following to `conf.py` (replace with the problematic URLs).

build_sphinx_docs/action.yml

@@ -12,6 +12,11 @@ inputs:
     required: false
     type: boolean
     default: true
+  use-make:
+    description: 'Use `make` with linkcheck and building html'
+    required: false
+    type: boolean
+    default: false
 
 runs:
   using: 'composite'
@@ -49,12 +54,22 @@ runs:
   - name: Check links
     if: ${{ inputs.check-links == 'true' }}
     shell: bash
-    run: sphinx-build docs/source docs/build -b linkcheck
+    run: | 
+      if [ ${{ inputs.use-make }} == 'true' ]; then
+        cd docs && make linkcheck
+      else
+        sphinx-build docs/source docs/build -b linkcheck
+      fi
 
   # needs to have sphinx.ext.githubpages in conf.py extensions list
   - name: Building documentation
     shell: bash
-    run: sphinx-build docs/source docs/build -b html
+    run: | 
+      if [ ${{ inputs.use-make }} == 'true' ]; then
+        cd docs && make html
+      else
+        sphinx-build docs/source docs/build -b html
+      fi
 
   - name: Upload the content for deployment
     uses: actions/upload-artifact@v4

deploy_sphinx_docs/README.md

@@ -5,4 +5,9 @@ The docs are then published (by default at `https://<username>.github.io/<repo>/
 The various steps include:
 * Removing any previous builds, if present in `docs/build`
 * downloading the built html pages (artifact named `docs-build`) into the `docs/build` folder (see the [Build Sphinx Docs action](../build_sphinx_docs/README.md))
-* deploying the`html` pages to the `gh-pages` branch. This step uses [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages).
+* deploying the`html` pages to the `gh-pages` branch. This step uses [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages).
+
+The `use-make` input is optional and defaults to `false`. 
+As this input helps to identify the location of the built documentation for deployment, it should match the `use-make` value specified in the [Build Sphinx Docs action](../build_sphinx_docs/README.md).
+If set to `true`, it is assumed that the documentation is built using `make` and the `./docs/build/html` directory will be used as the publish directory. 
+If set to `false`, the `./docs/build/` directory will be used instead.

deploy_sphinx_docs/action.yml

@@ -5,6 +5,13 @@ inputs:
   secret_input:
     description: 'The secret input for the GitHub token'
     required: true
+  use-make:
+    description: |
+      Specify whether `make` is used in the `build_sphinx_docs` action,
+      so that the correct publish directory is used
+    required: false
+    type: boolean
+    default: false
 
 runs:
   using: 'composite'
@@ -28,4 +35,4 @@ runs:
     uses: peaceiris/actions-gh-pages@v4
     with:
       github_token: ${{ env.GITHUB_TOKEN }}
-      publish_dir: ./docs/build
+      publish_dir: ${{ inputs.use-make == 'true' && './docs/build/html' || './docs/build/' }}