Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@SilverRainZ
SilverRainZ committed Dec 4, 2022
1 parent fdbc74c commit 0a11a7c
Show file tree
Hide file tree
Showing 3 changed files with 81 additions and 79 deletions.
111 changes: 54 additions & 57 deletions README.rst
View file
@@ -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
Expand All @@ -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 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
========
Expand Down
45 changes: 25 additions & 20 deletions action.yml
View file
Expand Up @@ -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
Expand All @@ -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 }}
Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions main.sh
View file
Expand Up @@ -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
Expand Down

0 comments on commit 0a11a7c

Please sign in to comment.