diff --git a/README.rst b/README.rst index c33c246..d9a4cf7 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ ========================= -Sphinx to GitHub Pages V2 +Sphinx to GitHub Pages V3 ========================= .. image:: https://img.shields.io/github/stars/sphinx-notes/pages.svg?style=social&label=Star&maxAge=2592000 @@ -10,66 +10,63 @@ Help you deploying your Sphinx documentation to Github Pages. Usage ===== -This action only help you build and commit Sphinx documentation to ``gh-pages``, -branch. So we need some other actions: - -- ``action/setup-python`` for installing python and pip -- ``actions/checkout`` for checking out git repository -- ``ad-m/github-push-action`` for pushing site to remote - -So your workflow file should be: - -.. code-block:: yaml - - name: Pages - on: - push: - branches: - - master - jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/setup-python@v2 - - uses: actions/checkout@master - with: - fetch-depth: 0 # otherwise, you will failed to push refs to dest repo - - name: Build and Commit - uses: sphinx-notes/pages@v2 - - name: Push changes - uses: ad-m/github-push-action@master - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - branch: gh-pages +1. `Set the publishing sources to "Github Actions"`__ + + .. note:: Publishing your GitHub Pages site with a custom GitHub Actions workflow is in beta and subject to change. + + __ https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow + +2. Create workflow: + + .. code-block:: yaml + + name: Deploy Sphinx documentation to Pages + + # Runs on pushes targeting the default branch + on: + push: + branches: [master] + + # Allow one concurrent deployment + concurrency: + group: "pages" + cancel-in-progress: true + + jobs: + pages: + runs-on: ubuntu-20.04 + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + permissions: + pages: write + id-token: write + steps: + - id: deployment + uses: sphinx-notes/pages@v3 Inputs ====== -======================= ============== ============ ============================= -Input Default Required Description ------------------------ -------------- ------------ ----------------------------- -``documentation_path`` ``'./docs'`` ``false`` Relative path under - repository to documentation - source files -``target_branch`` ``'gh-pages'`` ``false`` Git branch where assets will - be deployed -``target_path`` ``'.'`` ``false`` Directory in Github Pages - where Sphinx Pages will be - placed -``repository_path`` ``'.'`` ``false`` Relative path under - ``$GITHUB_WORKSPACE`` to - place the repository. - You not need to set this - Input unless you checkout - the repository to a custom - path -``requirements_path`` ``''`` ``false`` Relative path under - ``$repository_path`` to pip - requirements file -``sphinx_version`` ``''`` ``false`` Custom version of Sphinx -``cache`` ``false`` ``false`` Enable cache to speed up - documentation building -======================= ============== ============ ============================= +======================= ================================ ======== ============================= +Input Default Required Description +----------------------- -------------------------------- -------- ----------------------------- +``documentation_path`` ``./docs`` false Path to Sphinx source files +``requirements_path`` ``./docs/requirements.txt`` false Path to to requirements file +``python_version`` ``3.10`` false Version of Python +``sphinx_version`` ``5.3`` false Version of Sphinx +``cache`` ``false`` false Enable cache to speed up + documentation building +======================= =============================== ========= ============================ + +Outputs +====== + +======================= ====================================================================== +Output Description +----------------------- ---------------------------------------------------------------------- +``page_url`` URL to deployed GitHub Pages +======================= ====================================================================== Examples ======== diff --git a/action.yml b/action.yml index 78c8188..63b0bc6 100644 --- a/action.yml +++ b/action.yml @@ -7,25 +7,17 @@ branding: icon: 'upload-cloud' inputs: documentation_path: - description: 'Relative path under $repository_path to documentation source files' + description: 'Path to Sphinx source files' required: false default: './docs' - target_branch: - description: 'Git branch where Github Pages will be deployed' - required: false - default: 'gh-pages' - target_path: - description: 'Path in Github Pages where Sphinx Pages will be placed' - required: false - default: '.' - repository_path: - description: 'Relative path under $GITHUB_WORKSPACE to place the repository' - required: false - default: '.' requirements_path: - description: 'Relative path under $repository_path to pip requirements file' + description: 'Path to requirements file' required: false - default: './requirements.txt' + default: './docs/requirements.txt' + python_version: + description: 'Version of Python' + required: false + default: '3.10' sphinx_version: description: 'Version of Sphinx' required: false @@ -34,27 +26,42 @@ inputs: description: 'Enable cache to speed up documentation building' required: false default: false +outputs: + page_url: + description: 'URL to deployed GitHub Pages' + value: ${{ steps.deployment.outputs.page_url }} runs: using: "composite" steps: - name: Checkout uses: actions/checkout@v3 + if: ${{ inputs.cache == 'true' }} with: fetch-depth: 0 # Required by git-restore-mtime + - name: Checkout + uses: actions/checkout@v3 + if: ${{ inputs.cache == 'false' }} - name: Setup python uses: actions/setup-python@v4 + if: ${{ inputs.cache == 'true' }} with: - python-version: '3.10' + python-version: ${{ inputs.python_version }} cache: 'pip' + - name: Setup python + uses: actions/setup-python@v4 + if: ${{ inputs.cache == 'false' }} + with: + python-version: ${{ inputs.python_version }} - name: Restore cache uses: actions/cache@v3 if: ${{ inputs.cache == 'true' }} with: path: /tmp/sphinxnotes-pages - key: sphinxnotes-pages-${{ runner.os }}-${{ github.run_id }} # https://github.com/actions/cache/blob/main/tips-and-workarounds.md#update-a-cache + # https://github.com/actions/cache/blob/main/tips-and-workarounds.md#update-a-cache + key: sphinxnotes-pages-${{ runner.os }}-${{ github.run_id }} restore-keys: | sphinxnotes-pages-${{ runner.os }} @@ -64,11 +71,9 @@ runs: env: # See https://github.com/actions/runner/issues/665 INPUT_DOCUMENTATION_PATH: ${{ inputs.documentation_path }} - INPUT_TARGET_BRANCH: ${{ inputs.target_branch }} - INPUT_TARGET_PATH: ${{ inputs.target_path }} - INPUT_REPOSITORY_PATH: ${{ inputs.repository_path }} INPUT_REQUIREMENTS_PATH: ${{ inputs.requirements_path }} INPUT_SPHINX_VERSION: ${{ inputs.sphinx_version }} + INPUT_CACHE: ${{ inputs.cache }} - name: Setup Pages uses: actions/configure-pages@v2 diff --git a/main.sh b/main.sh index 506cc12..6a5c7bc 100755 --- a/main.sh +++ b/main.sh @@ -39,9 +39,9 @@ echo ::endgroup:: if [ ! -z "$INPUT_REQUIREMENTS_PATH" ] ; then echo ::group:: Installing requirements - if [ -f "$repo_dir/$INPUT_REQUIREMENTS_PATH" ]; then + if [ -f "$INPUT_REQUIREMENTS_PATH" ]; then echo Installing python requirements - pip3 install -r "$repo_dir/$INPUT_REQUIREMENTS_PATH" + pip3 install -r "$INPUT_REQUIREMENTS_PATH" else echo No requirements.txt found, skipped fi