GitHub Actions

[asmeurer]

We're in the GitHub actions beta.

I'm not sure if there's really much for doctr to potentially do with GitHub actions. I think it can be set up much easier to push to gh-pages, since it already has the permissions. Maybe it could be useful for the syncing stuff.

[asmeurer]

You can add actions to the marketplace. There are already some actions for GitHub pages, such as https://github.com/crazy-max/ghaction-github-pages, but they don't seem as well developed as doctr (e.g., the one I linked there uses personal access tokens instead of deploy keys). So I think we should make doctr work with actions and add it to the marketplace.

[navjotk]

We'd love to hear if someone has successfully used Doctr as part of a GitHub action, or if the recommended practice is something else entirely?

[CAM-Gerlach]

@asmeurer Now that Travis CI just announced that they are no longer going to be free for open source beyond a fixed number of trial minutes that don't renew, the mass migration to Github actions is likely to intensify, and we're going to have to do so at some point soon for spyder-ide/spyder-docs . Any plans for this, and any ways we can help (time, funding, testing, etc)? Or is there an alternative for Github actions you would recommend? Thanks!

[asmeurer]

I'm open to adding support for any public CI system to doctr. GitHub actions seems like a common alternative. I think we should try to get it set up so that it is in the marketplace.

I don't know how much time I will have myself to work on it, though, so if someone wants to pick up the work, please do. I can answer any questions and help review things, and also give people push access if it is needed.

[asmeurer]

I should note that there are already some things on the GitHub actions marketplace that push to GitHub pages. But none of the options I saw handle things as nicely as doctr, so there's still room for doctr to do better.

[CAM-Gerlach]

@ccordoba12 's going to talk to you about it to see what we can work out. Thanks!

[goerz]

Since Travis now no longer supports OSS at all, cf #371 (comment), moving to Github Actions seems inevitable. I played around briefly with deploying documentation to gh-pages from a Github Action. Since the action is already authenticated to push back to the repo, it turned out to be quite easy without using doctr at all.

Still, I kind of would love to keep the "doctr" package involved, mostly because otherwise it would make the branding of my doctr_versions_menu package (which is still used in the Action) a little awkward ;-) Thus, I'd be rather enthusiastic about seeing the doctr package consolidate and include something like the steps I've now done manually in the Github Action.

[asmeurer]

So you don't need a deploy key to push to gh-pages from GitHub actions? I have a WIP at #372 but it's basically reusing the exact same logic as Travis.

If we don't need a deploy key, that's interesting. I haven't seen any examples like that before. If that's the case guess doctr could still be useful for its syncing.

Either way, I haven't had a chance to continue work on this. If you want to pick it up, let me know.

[goerz]

Yes, I was pleasantly surprized to find out that apparently you don't need a deploy key for any action that involves only the repository that triggered the workflow. A "git push" works directly, and for marketplace actions it seems there is a pre-defined GITHUB_TOKEN, see https://docs.github.com/en/free-pro-team@latest/actions/reference/authentication-in-a-workflow. Stuff like making releases and uploading artifacts to Github also seem to work out of the box. Based on my limited experience with Github Actions, it's actually a much better system than Travis ever was. Still, I kind of have better things to do than having to worry about moving all my projects off Travis.

If I understand that documentation correctly, for use cases where there is a separated "docs" repo, i.e. you're not pushing to the repo that triggered the workflow, you'd still need a separate deploy key, though. I suppose Doctr would still want to cover that use case, although it's not something I'd use, personally.

I don't think I'll be available to work on GH Actions integration for Doctr directly in the near future, but if @ccordoba12 and @CAM-Gerlach are still on this, I would very much approve (and be happy to test it in the context of doctr-versions-menu)

[asmeurer]

I see, so we still need the full logic for pushing to another repo, which is an important use-case.

I think for my PR, we mainly need to set up the GitHub actions yaml file, with all the same tests as from the Travis file. And we also should implement the logic for not needing a deploy key for the same repo (should be easy).

[oscarbenjamin]

I was just thinking about migrating SymPy's doctr job from Travis to Actions but I wasn't actually sure what doctr was. I've just taken a little time to go through the README here, read a few issue like this one, and look at alternatives in the actions marketplace. I hadn't realised until reading the README that doctr was designed very specifically for Travis and can't immediately be used with Actions.

I see that there is #372 which looks to make it possible to use doctr with Actions but seems to have stalled 2 months ago. I'm not familiar with this repo but from a quick glance the PR looks like a complete rewrite of this codebase.

There are alternatives in the Actions marketplace that seem to be used. The one linked above is:
https://github.com/crazy-max/ghaction-github-pages
which only works for pushing to the same repo or uses personal access tokens. The primary purpose of doctr (at least from the README) is to work with deploy keys so that is not quite a replacement for doctr.

There are other possibilities though:
https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-deploy-to-external-repository-external_repository

Note both of those are projects that are aimed at Github pages specifically but actually all that's really needed is something to handle the secrets involved in pushing to another repo. There are also generic "push to repo" actions available (these are just first hits from a google search for "github actions push to another repo" - I saw more developed looking ones earlier but don't have the links handy):
https://github.com/marketplace/actions/push-directory-to-another-repository
https://github.com/marketplace/actions/github-action-to-push-subdirectories-to-another-repo
https://github.com/marketplace/actions/push-a-file-to-another-repository

I'm wondering now if the rationale for using doctr would still apply even if it was currently usable with Actions. At least packages are still needed for this purpose (pushing from CI) but there are others that can do this for Actions that have immediate advantages:

1. Designed specifically for Actions (i.e. they are implemented as actions)
2. Immediately available in the marketplace (no install needed)
3. Actively maintained (lots of contributors, regular issues and releases)
4. Working right now

I haven't looked very hard and haven't tried anything but from a quick skim of options my current favourite is:
https://github.com/marketplace/actions/github-pages-action

[oscarbenjamin]

I haven't looked very hard and haven't tried anything but from a quick skim of options my current favourite is:
https://github.com/marketplace/actions/github-pages-action

Yep, that's the way to go. I've made a demo here:
https://github.com/oscarbenjamin/actions_docs_build_demo

I've probably overcomplicated things by using artifacts in that demo. If you already have an actions config that has a job that builds the docs then the deploy step is just something like:

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: sympy/sympy_docs
          publish_dir: ./doc/src/_build/html
          publish_branch: gh-pages

Obviously you need to actually set up the deploy keys for the two repos for that to work though. From the README in the demo:

Create public/private SSH keys:

 $ ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""

This create ``gh-pages`` (private key) and ``gh-pages.pub`` (public key).

Upload the private key to the code repo as a "deploy key". Upload the public
key to the docs repo as a "repository secret" with the environment variable
name ``ACTIONS_DEPLOY_KEY`` and give it write access. Instructions here:

https://github.com/marketplace/actions/github-pages-action#%EF%B8%8F-create-ssh-deploy-key

The reason I used artifacts in the demo is because it makes it possible to download the built docs for a PR once the Actions checks have completed which I think would be useful. We also probably want to use artifacts for other things like the benchmark/coverage reports.

[CAM-Gerlach]

For another example, we ported spyder-ide/spyder-docs from Doctr to Github Actions in spyder-ide/spyder-docs#218 ; on one hand, we deploy to the gh-pages branch of the same repo so we didn't need the extra deploy key setup, but our implementation showcases some additional GH actions features and demonstrates a few additional use cases:

• We were using both Travis (for test/deploy, which we replaced by Github Actions) and Netlify (for preview generation), with common install, build and deploy shell scripts shared by both (which in turn did most of their real business in portable Python scripts); this is a great idea if you want to minimize the bespoke/redundant config for each CI platform and makes using multiple and porting to a different one easier
• We split the build + test (for PRs) and build + deploy (for pushes to master) into separate workflows that only run when the respective event occurs (so that e.g. a transient linkcheck failure doesn't stop the deploy), sharing common install and build actions to be DRY/modular (perhaps a little overkill for now, but makes it easy to modify in the future)
• The build tests, linkcheck and static pre-commit hooks all run as separate jobs in parallel, significantly speeding up execution and allowing for easy scaling in the future, as well as indicating their status separately (so we can see at a glance if a failure indicates a fatal build problem, a broken link or just a style nitpick
• We have some orchestration scripts running on top of Sphinx to handle multi-version support (like ReadTheDocs), redirect generation and a few other tasks, but as these were cross-platform Python and all handled by the makefile, which was in turn run by the existing shell scripts, this was transparent to the port (ideally, we should port the makefile itself to be a Python script or something else portable, but that's for the future)

We used JamesIves/github-pages-deploy-action since we saw it recommended elsewhere, it has about the same number of stars and actively developed but not sure if there's a clear winner between the two.

[asmeurer]

Part of the original motivation for doctr is setting up the deploy key stuff for you. I'm glad to see that action is using a deploy key. When I looked a year ago, all the options on the marketplace were using personal access tokens, which are worse (a deploy key gives access to a single repo, whereas a personal access token gives full access to all the repos of the person who created it). I'm not a fan of how either peaceiris/actions-gh-pages or JamesIves/github-pages-deploy-action recommend using a personal access token at all. They should generally be avoided.

[ocefpaf]

@asmeurer also, doctr handles versioned docs in an elegant way. It took me quite a few steps to achieve the same with those GHA. So the key setup is not the only advantage.

[CAM-Gerlach]

Part of the original motivation for doctr is setting up the deploy key stuff for you.

Yeah, and for the simple case of deploying to the gh-pages branch of the same repo, Github Actions makes that trivial (deploying to a different repo is not quite as easy as with doctr, though).

doctr handles versioned docs in an elegant way.

I'd be very interested to understand how you handled versioned docs, @ocefpaf , since we had to devote quite a bit of effort to that issue. At least how we had it set up (with Sphinx-Multiversion), it was completely orthogonal to doctr and was all handled by our build system and scripts, and was completely transparent to the deploy and CI layer such that no changes were needed to any of that when we ported over to Github Actions, . Perhaps that had to do with the basic design of Sphinx-Multiversion, with all the docs built simultaneously rather than independently by branch.

[goerz]

@CAM-Gerlach Not the OP, but this is where I'd like to plug Doctr Versions Menu

[CAM-Gerlach]

Ah, I see—thanks @goerz . Its too bad we weren't aware of that when we added multiversion support some months back; it takes a very different approach from Sphinx-Multiversion (making multi-version support part of the deploy rather than the build stage, and operating on each branch individually rather than orchestrating one synchronized pipeline) that has some advantages and disadvantages, but certainly would have been worth considering as an option.

However, especially for a basic use case (deploying to a gh-pages branch on the same repo), how come it recommends reimplementing all the steps to deploy to Github pages manually, as opposed to using an existing pre-built, tested and supported action? Also, I'm curious as to the benefits of running two separate jobs and zipping and uploading the built site as an artifact from one and downloading and unzipping it in the other that would outweigh the significant complexity and run time/resource hit? All told, it seems like a pretty large amount of bespoke code, complexity and run time for such a simple use case, when all of that could be accomplished in perhaps a couple dozen lines instead of 140 (and with way less finicky and difficult to maintain bash scripts). Is there a reason why something like the following couldn't work instead?

name: Docs
on: [push]
jobs:
    deploy_docs:
    name: Build Sphinx docs
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        name: Install Python 3.8
        with:
          python-version: 3.8
      - name: Install Tox and other build requirements
        run: pip install tox zip-files
      - name: Run Tox
        run: tox -e docs
      - name: Run doctr-versions-menu
        run: doctr-versions-menu
      - name: Deploy to GitHub Pages
        uses: JamesIves/[email protected]
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages # The branch the action should deploy to
          FOLDER: <BUILD_DIRECTORY> # The folder the action should deploy

[CAM-Gerlach]

Also, @asmeurer the JamesIves GH pages action does describe step by step how to use it with a deploy key; its certainly more involved than using Doctr and I'd miss having it there, but its mostly the same underlying process (just without Doctr's automation and nicities), and not as tricky as with Travis I don't think. It does also mention use with an access token, but it doesn't actually describe the specifics, rather referring users to the general Github docs if they are interested in that route.

[goerz]

I've only recently (since around December, when Travis effectively shut down) started to move from Travis to Github Actions. Right now, the "recommendations" I put in Doctr-Versions-Menu for using it with Github Actions are basically just what I've cooked up personally, and tried out in some projects (e.g. krotov and the slightly more elaborate qalgebra). They're not necessarily best practice and I'm very open to figuring out better ways to do this, like using an existing Marketplace Action.

I'm actually also waiting to see how Doctr will ultimately decide to deal with support for Github Actions. If Doctr eventually provides its own Action for everything, I'd probably want to use that. If not, that is if Doctr remains focused on Travis, which I'm not going to support going forward, I'm likely to rename "Doctr-Versions-Menu" to "Docs-Versions-Menu" and focus its documentation on deployment with Github Actions.

So far, my "manual" approach seemed relatively straightforward to me. It seemed like existing actions for deploying to Github Pages wouldn't be helping much, really only replacing the "rsync" step. There's some "nice" optional stuff I'm doing like generating the _downloads file with links to the packaged documentation, and amending when committing to gh-pages. This actually is the majority of the pipeline. Most importantly, though, and this the big caveat that I'm seeing with existing Actions and the pipeline you posted above: doctr-versions-menu needs to run on a checkout of the gh-pages branch, not on a checkout of the branch where tox -e docs runs. That's because it generates the menu from all the folders it sees on gh-pages. To be useful, the JamesIves/github-pages-deploy-action would need to have the option to run a command on the gh-pages branch after it deploys to it.

Again, I'm open to switching to an appropriate Action, or even possibly writing one. I'm personally really only interested in the "simple" case of deploying to the gh-pages branch of the same repository though, so if Doctr wants to evolve into an Action that also does deployment to a different repo, there's certainly room for that.

[goerz]

The reason why there are two jobs: I always want to build the documentation, even on pull-requests and topic branches, to make sure that it works. However, I only want to deploy to gh-pages from master and for tagged releases. It seemed easiest to separate these two things into different jobs, and to transfer documentation between them as a built-artifact

Anyway, I don't want to hijack this thread too much... You can open an issue on the doctr-versions-menu repo or just email me to discuss this further.

[asmeurer]

Hi all. As you've probably noticed, very little progress has been made on this. I've basically been too busy to work on this. Heavy development on doctr is very time consuming, as it requires a lot of manual testing.

If people still want to see doctr updated for GH Actions, most likely someone else will need to pick up the work on #372 (or start anew if that seems simpler). If someone is interested in working on it, I'd be happy to give you the necessary permissions to make it happen.

[CAM-Gerlach]

Thanks for the update, @asmeurer. As I understand it, the advantages/features of doctr centered around automatically and securely generating and handling the necessary deploy key to allow pushing the built docs to the correct branch on the desired repo.

Nowadays, the JamesIves/github-pages-deploy-action has added and simplified the authentication functionality with v4.0, allowing deploying to the same repo (the most common case) with no extra configuration and fully supporting both token and ssh-key authentication for deployment to a different one with relatively simple and documented setup. peaceiris/gihtub-pages-action offers very similar functionality as well. Both seem to offer most of the additional features/configuration doctr does, including custom deploy branch, repo, directory, etc., selection of what branches/tags to build from, exclude of files, etc.

The main things it appears doctr offers over these options are walking the user through the process of running the ssh-keygen command, adding the deploy key to their repo and (assuming its possible) adding it as a secret, saving some amount of time in the initial setup, as well as simplifying running a command on the remote repo (which is possible with Github Actions, though with some additional steps/hassle). On the other hand, these alternatives offer some additional features, e.g. setting the git username and email, custom commit messages, creating a git tag, squashing history, auto-adding CNAME and .nojekyll, option cleanup/keep of deleted files, etc. Is there anything else I'm missing from the former list?

Other than adding support for running a command on the remote repo (@goerz 's use case), given these existing actions pretty much cover the deployment functionality, maybe it would be more sustainable to focus doctr more tightly on just providing the configure functionality, for generating the deploy key, authorizing it with the repo and adding it as a secret, and then outputting the relevant lines of config for JamesIves/peaceiris's existing deploy actions? For that, the only changes needed, it would seem, is just adding the relevant API calls to add the deploy key as a secret to a Github repo, remove the code to output the now-unnecessary .enc file, and changing the routine that outputs the Travis config to instead output the relevant config for the Github pages actions (though since that's static and documented, it might not even be fully necessary, though simple to add).

Unfortunately I can't commit time right now to implementing it, especially since I'm familiar with doing it myself, but it would focus on the part of doctr that offers the most value over existing options, and requires the least changes to get working. Any thoughts on that approach?

[asmeurer]

I haven't used GitHub actions deploying enough to comment fully, but that sounds reasonable. The main point of doctr was always to handle the secrets stuff for you, since doing it manually is a huge pain, and you're liable to mess things up in a way that leaks account secrets. Another advantage is that doctr will always prefer the deploy key method over creating a token, unless explicitly told to. Deploy keys provide push access only to a single repo, whereas if a token leaks, it's like leaking your GitHub password. Deploy keys can also easily be revoked by anyone with push access.

The syncing functionality of doctr is also useful, that is, being able to place files in the root of gh-pages, and correctly doing things like deleting files. It's not all that complicated, but is more work than simply cp -R. I don't know how the existing GitHub Actions scripts handle that. And yes, lots of little things like automatically adding .nojekyll and adding a helpful deploy commit message that aren't major, but really helpful to have.