Try it on your fork

The quickest way to try sphinx-redline is on your own fork of its repository: the documentation you are reading is already set up for it, so you only need a token, a passphrase and a few clicks in GitHub. Everything happens in your fork; nothing is sent to the upstream repository.

You need a GitHub account. Allow about fifteen minutes.

Note

For simplicity, this tutorial keeps the comments in the fork itself. The guest token can therefore also push to your fork’s other branches, which is fine for a throwaway fork but not for real documentation; see Setting up for the safer setup with a separate comments repository.

1. Fork the repository

Open https://github.com/patrickerich/sphinx-redline and click Fork. Uncheck Copy the main branch only, so the fork also gets the redline branch with the example comments and the workflow that rebuilds the documentation when a comment arrives.

If you forked with only the main branch, create an empty comments branch instead:

git clone https://github.com/<you>/sphinx-redline
cd sphinx-redline
git switch --orphan redline
git commit --allow-empty -m "Start the comments branch"
git push origin redline

(Without the rebuild workflow you then start the documentation build by hand after commenting; see step 6.)

2. Turn on Actions and Pages

GitHub disables workflows in new forks.

  1. In your fork, open the Actions tab and confirm that you want to enable workflows.

  2. Open Settings → Pages and set Source to GitHub Actions.

3. Create a token for the comments

Open GitHub’s fine-grained token page and create a token with:

  • Repository access: Only select repositories, and select your fork only.

  • Permissions → Contents: Read and write.

  • An expiration date that suits you.

Copy the token (it starts with github_pat_).

4. Create the guest key

Open the guest key tool (it runs entirely in your browser; the token is not sent anywhere). Paste the token, click Generate for a passphrase, and click Create guest key. Keep the passphrase: you need it to comment.

In your fork, open Settings → Secrets and variables → Actions → Variables and add a repository variable named REDLINE_GUEST_KEY with the key as its value.

5. Build the documentation

Open Actions → docs → Run workflow. When it has finished, your copy of this documentation is published at https://<you>.github.io/sphinx-redline/.

6. Add a comment

  1. Open https://<you>.github.io/sphinx-redline/example.html.

  2. Select a few words in a paragraph and click the Comment button that appears below them.

  3. In the comment panel, enter your name and the passphrase and click Sign in as guest.

  4. Write the comment and click Save comment.

The comment is committed to your redline branch as comments/<id>.json; have a look at the branch on GitHub. You see it on the page straight away, marked “saved, not yet built”. The commit starts a new documentation build (see the Actions tab); when that is done, the comment is part of the published page for everyone. If your fork has no rebuild workflow, run the docs workflow again by hand.

Reply to the thread, or resolve it, the same way.

7. Change the text and watch the comment follow

Edit docs/source/example.rst on your fork’s main branch, for example by adding a paragraph above the one you commented on, and commit. After the documentation build, the comment is still on its text. Then reword or delete the commented sentence: the comment moves to the Outdated list in the panel instead of disappearing.

Cleaning up

Delete the token on GitHub’s token page when you are done, and delete the fork if you no longer need it.