From 510234123a2a6231cc9f6a4045801ef99ff5923e Mon Sep 17 00:00:00 2001 From: Chang Huan Lo Date: Tue, 30 Jul 2024 08:54:40 +0100 Subject: [PATCH] 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 | 5 +++++ build_sphinx_docs/README.md | 10 ++++++++-- build_sphinx_docs/action.yml | 19 +++++++++++++++++-- deploy_sphinx_docs/README.md | 7 ++++++- deploy_sphinx_docs/action.yml | 9 ++++++++- 5 files changed, 44 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 1b88a44..41dee6c 100644 --- a/README.md +++ b/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). diff --git a/build_sphinx_docs/README.md b/build_sphinx_docs/README.md index 0f436a0..3ee0d57 100644 --- a/build_sphinx_docs/README.md +++ b/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). diff --git a/build_sphinx_docs/action.yml b/build_sphinx_docs/action.yml index f1d87ab..e4612cb 100644 --- a/build_sphinx_docs/action.yml +++ b/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 diff --git a/deploy_sphinx_docs/README.md b/deploy_sphinx_docs/README.md index faa603d..5b04456 100644 --- a/deploy_sphinx_docs/README.md +++ b/deploy_sphinx_docs/README.md @@ -5,4 +5,9 @@ The docs are then published (by default at `https://.github.io// 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). \ No newline at end of file +* 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. \ No newline at end of file diff --git a/deploy_sphinx_docs/action.yml b/deploy_sphinx_docs/action.yml index 1014730..5e31c8a 100644 --- a/deploy_sphinx_docs/action.yml +++ b/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/' }}