mirror of
https://github.com/element-hq/synapse
synced 2024-07-07 00:53:29 +00:00
f0e02f5df2
Currently when a new build of the docs is created, an `index.html` file does not exist. Typically this would be generated from a`docs/README.md` file - which we have - however we're currently using [docs/README.md](394673055d/docs/README.md) to explain the docs and point to the website. It is not part of the content of the website. So we end up not having an `index.html` file, which will result in a 404 page if one tries to navigate to `https://matrix-org.github.io/synapse/<docs_version>/index.html`. This isn't a really problem for the default version of the documentation (currently `develop`), as [navigating to the top-level root](https://matrix-org.github.io/synapse/) of the website (without specifying a version) will [redirect](a77e6925f2/index.html (L2)) you to the Welcome and Overview page of the `develop` docs version. However, ideally once we add a GUI for switching between versions, we'll want to send the user to `matrix-org.github.io/synapse/<version>/index.html`, which currently isn't generated. This PR modifies the CI that builds the docs to simply copy the rendered [Welcome & Overview page](https://matrix-org.github.io/synapse/develop/welcome_and_overview.html) to `index.html`.
70 lines
2.8 KiB
YAML
70 lines
2.8 KiB
YAML
name: Deploy the documentation
|
|
|
|
on:
|
|
push:
|
|
branches:
|
|
# For bleeding-edge documentation
|
|
- develop
|
|
# For documentation specific to a release
|
|
- 'release-v*'
|
|
|
|
workflow_dispatch:
|
|
|
|
jobs:
|
|
pages:
|
|
name: GitHub Pages
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v2
|
|
|
|
- name: Setup mdbook
|
|
uses: peaceiris/actions-mdbook@4b5ef36b314c2599664ca107bb8c02412548d79d # v1.1.14
|
|
with:
|
|
mdbook-version: '0.4.9'
|
|
|
|
- name: Build the documentation
|
|
# mdbook will only create an index.html if we're including docs/README.md in SUMMARY.md.
|
|
# However, we're using docs/README.md for other purposes and need to pick a new page
|
|
# as the default. Let's opt for the welcome page instead.
|
|
run: |
|
|
mdbook build
|
|
cp book/welcome_and_overview.html book/index.html
|
|
|
|
# Deploy to the latest documentation directories
|
|
- name: Deploy latest documentation
|
|
uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0
|
|
with:
|
|
github_token: ${{ secrets.GITHUB_TOKEN }}
|
|
keep_files: true
|
|
publish_dir: ./book
|
|
destination_dir: ./develop
|
|
|
|
- name: Get the current Synapse version
|
|
id: vars
|
|
# The $GITHUB_REF value for a branch looks like `refs/heads/release-v1.2`. We do some
|
|
# shell magic to remove the "refs/heads/release-v" bit from this, to end up with "1.2",
|
|
# our major/minor version number, and set this to a var called `branch-version`.
|
|
#
|
|
# We then use some python to get Synapse's full version string, which may look
|
|
# like "1.2.3rc4". We set this to a var called `synapse-version`. We use this
|
|
# to determine if this release is still an RC, and if so block deployment.
|
|
run: |
|
|
echo ::set-output name=branch-version::${GITHUB_REF#refs/heads/release-v}
|
|
echo ::set-output name=synapse-version::`python3 -c 'import synapse; print(synapse.__version__)'`
|
|
|
|
# Deploy to the version-specific directory
|
|
- name: Deploy release-specific documentation
|
|
# We only carry out this step if we're running on a release branch,
|
|
# and the current Synapse version does not have "rc" in the name.
|
|
#
|
|
# The result is that only full releases are deployed, but can be
|
|
# updated if the release branch gets retroactive fixes.
|
|
if: ${{ startsWith( github.ref, 'refs/heads/release-v' ) && !contains( steps.vars.outputs.synapse-version, 'rc') }}
|
|
uses: peaceiris/actions-gh-pages@v3
|
|
with:
|
|
github_token: ${{ secrets.GITHUB_TOKEN }}
|
|
keep_files: true
|
|
publish_dir: ./book
|
|
# The resulting documentation will end up in a directory named `vX.Y`.
|
|
destination_dir: ./v${{ steps.vars.outputs.branch-version }}
|