Skip to content

Commit 1a5549e

Browse files
mcmiremcmire
authored
Add docsite (#225)
`docs/` now holds Markdown files that will be published to a docsite generated by `mkdocs` and hosted on GitHub Pages. Using `mkdocs` allows us to try out literate programming. This requires Python, so that's been added to the `setup` script. Thanks to some new GitHub actions, provided there have been any changes to the docs, a preview version of the docsite will be automatically published when a pull request is updated (in which case the URL will be `https://mcmire.github.io/super_diff/branches/<branch-name>/<commit.id>`), and a release version will be published when a release PR is merged (in which case it will be `https://mcmire.github.io/super_diff/releases/<version>`). Any preview version that have been previously been created for a pull request will be deleted when that pull request is closed. The CONTRIBUTING and ARCHITECTURE docs have been moved into `docs/` and expanded to not only explain how SuperDiff works but also the RSpec integration.
1 parent 1c86d63 commit 1a5549e

28 files changed

+1411
-276
lines changed

‎.editorconfig‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,5 @@ indent_size = 2
1111
[*.{rb,js}]
1212
max_line_length = 80
1313

14-
[README.md]
14+
[*.md]
1515
max_line_length = unset

‎.github/workflows/super_diff.yml‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ on:
77
pull_request:
88
types:
99
- opened
10+
- closed
1011
- reopened
1112
- synchronize
1213
concurrency:
@@ -15,6 +16,7 @@ concurrency:
1516
jobs:
1617
analyze:
1718
runs-on: ubuntu-latest
19+
if: ${{ github.event_name == 'push' || github.event.action != 'closed' }}
1820
steps:
1921
- uses: actions/checkout@v4
2022
- name: Download actionlint
@@ -88,3 +90,179 @@ jobs:
8890
- test
8991
steps:
9092
- run: echo "Analysis and tests passed. Ready to merge."
93+
94+
collect-release-info:
95+
runs-on: ubuntu-latest
96+
steps:
97+
- uses: actions/checkout@v4
98+
- name: Set up Ruby
99+
uses: ruby/setup-ruby@v1
100+
with:
101+
bundler-cache: true
102+
- name: Run command
103+
id: command
104+
run: scripts/collect-release-info.rb
105+
outputs:
106+
IS_NEW_RELEASE: ${{ steps.command.outputs.IS_NEW_RELEASE }}
107+
RELEASE_VERSION: ${{ steps.command.outputs.RELEASE_VERSION }}
108+
109+
collect-docsite-release-info:
110+
runs-on: ubuntu-latest
111+
needs:
112+
- collect-release-info
113+
steps:
114+
- uses: actions/checkout@v4
115+
with:
116+
fetch-depth: 0
117+
- name: Run command
118+
id: command
119+
run: |
120+
set -x
121+
122+
if [[ "$IS_NEW_RELEASE" == "true" ]]; then
123+
DOCSITE_RELEASE_VERSION="$RELEASE_VERSION"
124+
DOCSITE_DESTINATION_PATH="releases/$RELEASE_VERSION"
125+
HAS_CHANGES_TO_DOCS="true"
126+
else
127+
DOCSITE_RELEASE_VERSION="$COMMIT_ID"
128+
DOCSITE_DESTINATION_PATH="branches/$BRANCH_NAME/$COMMIT_ID"
129+
# Check if there any changes to docs/
130+
if git diff --quiet --merge-base "origin/$GITHUB_BASE_REF" -- docs; then
131+
HAS_CHANGES_TO_DOCS="false"
132+
else
133+
HAS_CHANGES_TO_DOCS="true"
134+
fi
135+
fi
136+
137+
{
138+
echo "DOCSITE_RELEASE_VERSION=$DOCSITE_RELEASE_VERSION"
139+
echo "DOCSITE_DESTINATION_PATH=$DOCSITE_DESTINATION_PATH"
140+
echo "HAS_CHANGES_TO_DOCS=$HAS_CHANGES_TO_DOCS"
141+
} >> "$GITHUB_OUTPUT"
142+
env:
143+
IS_NEW_RELEASE: ${{ needs.collect-release-info.outputs.IS_NEW_RELEASE }}
144+
RELEASE_VERSION: ${{ needs.collect-release-info.outputs.RELEASE_VERSION }}
145+
BRANCH_NAME: ${{ github.head_ref }}
146+
COMMIT_ID: ${{ github.event.pull_request.head.sha }}
147+
outputs:
148+
DOCSITE_RELEASE_VERSION: ${{ steps.command.outputs.DOCSITE_RELEASE_VERSION }}
149+
DOCSITE_DESTINATION_PATH: ${{ steps.command.outputs.DOCSITE_DESTINATION_PATH }}
150+
HAS_CHANGES_TO_DOCS: ${{ steps.command.outputs.HAS_CHANGES_TO_DOCS }}
151+
152+
build-docsite:
153+
runs-on: ubuntu-latest
154+
needs:
155+
- analyze
156+
- collect-release-info
157+
- collect-docsite-release-info
158+
if: ${{ github.event_name == 'pull_request' && ((needs.collect-release-info.outputs.IS_NEW_RELEASE == 'false' && needs.collect-docsite-release-info.outputs.HAS_CHANGES_TO_DOCS == 'true') || (needs.collect-release-info.outputs.IS_NEW_RELEASE == 'true' && github.event.merged)) }}
159+
steps:
160+
- uses: actions/checkout@v4
161+
- name: Install poetry
162+
run: pipx install poetry
163+
- name: Set up Python
164+
uses: actions/setup-python@v5
165+
- name: Install Python dependencies
166+
run: poetry install
167+
- name: Build docsite
168+
run: poetry run mkdocs build
169+
- name: Save site/ for later jobs
170+
uses: actions/cache/save@v3
171+
with:
172+
path: site
173+
key: docsite-${{ github.sha }}
174+
175+
publish-docsite:
176+
runs-on: ubuntu-latest
177+
needs:
178+
- collect-release-info
179+
- collect-docsite-release-info
180+
- build-docsite
181+
steps:
182+
- uses: actions/checkout@v4
183+
with:
184+
ref: gh-pages
185+
- name: Restore cache from previous job
186+
uses: actions/cache/restore@v3
187+
with:
188+
path: site
189+
key: docsite-${{ github.sha }}
190+
- name: Update redirect in index (for a release)
191+
if: ${{ needs.collect-release-info.outputs.IS_NEW_RELEASE == 'true' }}
192+
run: |
193+
cat <<-EOT > index.html
194+
<!DOCTYPE html>
195+
<html>
196+
<head>
197+
<title>SuperDiff Documentation</title>
198+
<meta http-equiv="refresh" content="0; url='https://mcmire.github.com/super_diff/releases/${RELEASE_VERSION}'" />
199+
</head>
200+
<body>
201+
<p>
202+
This page has moved to a different URL.
203+
Please click
204+
<a href="https://mcmire.github.com/super_diff/releases/${RELEASE_VERSION}">
205+
this link
206+
</a>
207+
if you are not redirected.
208+
</p>
209+
</body>
210+
</html>
211+
EOT
212+
- name: Copy site/ to ${{ needs.collect-docsite-release-info.outputs.DOCSITE_DESTINATION_PATH }}
213+
run: |
214+
mkdir -p "$(dirname "$DOCSITE_DESTINATION_PATH")"
215+
mv site "$DOCSITE_DESTINATION_PATH"
216+
env:
217+
DOCSITE_DESTINATION_PATH: ${{ needs.collect-docsite-release-info.outputs.DOCSITE_DESTINATION_PATH }}
218+
- name: Publish new version of docsite
219+
run: |
220+
git add -A .
221+
git config user.name "${GITHUB_ACTOR}"
222+
git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
223+
git commit -m "Publish docs at $DOCSITE_DESTINATION_PATH"
224+
git push
225+
env:
226+
DOCSITE_DESTINATION_PATH: ${{ needs.collect-docsite-release-info.outputs.DOCSITE_DESTINATION_PATH }}
227+
- name: Announce publishing of docsite as a comment on the PR
228+
run: |
229+
gh pr comment "$PULL_REQUEST_NUMBER" --body ":book: A new version of the docsite has been published at: <https://mcmire.github.io/super_diff/$DOCSITE_DESTINATION_PATH>"
230+
env:
231+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
232+
PULL_REQUEST_NUMBER: ${{ github.event.number }}
233+
DOCSITE_DESTINATION_PATH: ${{ needs.collect-docsite-release-info.outputs.DOCSITE_DESTINATION_PATH }}
234+
235+
unpublish_docsite:
236+
runs-on: ubuntu-latest
237+
needs:
238+
- collect-release-info
239+
- collect-docsite-release-info
240+
if: ${{ github.event_name == 'pull_request' && needs.collect-release-info.outputs.IS_NEW_RELEASE == 'false' && github.event.action == 'closed' }}
241+
steps:
242+
- uses: actions/checkout@v4
243+
with:
244+
ref: gh-pages
245+
- name: Set DOCSITE_DESTINATION_PARENT_PATH
246+
run: |
247+
set -x
248+
DOCSITE_DESTINATION_PARENT_PATH="$(dirname "$DOCSITE_DESTINATION_PATH")"
249+
echo "DOCSITE_DESTINATION_PARENT_PATH=$DOCSITE_DESTINATION_PARENT_PATH" >> "GITHUB_ENV"
250+
env:
251+
DOCSITE_DESTINATION_PATH: ${{ needs.collect-docsite-release-info.outputs.DOCSITE_DESTINATION_PATH }}
252+
- name: Remove ${{ env.DOCSITE_DESTINATION_PARENT_PATH }} on gh-pages
253+
run: |
254+
set -x
255+
if [[ "$DOCSITE_DESTINATION_PARENT_PATH" == "releases" || "$DOCSITE_DESTINATION_PARENT_PATH" == "branches" ]]; then
256+
echo "Not removing $DOCSITE_DESTINATION_PARENT_PATH."
257+
exit 1
258+
fi
259+
rm -rf "$DOCSITE_DESTINATION_PARENT_PATH"
260+
- name: Re-push docsite if necessary
261+
run: |
262+
git add -A .
263+
if ! git diff --cached --quiet; then
264+
git config user.name "${GITHUB_ACTOR}"
265+
git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
266+
git commit -m "Remove $DOCSITE_DESTINATION_PARENT_PATH"
267+
git push
268+
fi

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,9 @@ zeus.server-start.log
1818
!.yarn/releases
1919
!.yarn/sdks
2020
!.yarn/versions
21+
22+
# Ignore Python stuff
23+
poetry.lock
24+
25+
# Ignore mkdocs stuff
26+
site

‎.prettierignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
.yarn/cache
22
.yarn/releases
33
gemfiles
4+
site
5+
tmp
46
vendor/bundle
57
yarn.lock

‎.python-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.12.2

‎ARCHITECTURE.md‎

Lines changed: 0 additions & 33 deletions
This file was deleted.

‎CONTRIBUTING.md‎

Lines changed: 0 additions & 72 deletions
This file was deleted.

0 commit comments

Comments
 (0)