search

readthedocs / actions

GitHub Actions for Read the Docs
MIT License
33 stars 10 forks source link

PR description not created on push of documentation files #41

Open stevepiercy opened 3 months ago

stevepiercy commented 3 months ago

First, when a pull request is opened and it contains documentation files as defined in the GitHub workflow defined below, the pull request's description updates with a link to the pull request preview build. This is good.

name: readthedocs/actions
on:
  pull_request_target:
    types:
      - opened
    # Execute this action only on PRs that touch
    # documentation files.
    paths:
      - "docs/source/**"
      - .readthedocs.yaml
      - requirements-docs.txt

However, if there are no documentation files when the pull request is opened, but later documentation files are pushed to the pull request in subsequent commits, then the action does not run and the description is not updated. I assume many developers write code first, then later add documentation to their pull request if they add it at all.

It would be good to update the documented example workflow file to run on both pull_request_target and push on changes to documentation-related files. Unfortunately I don't know how to do that.

I tried moving it into jobs.<job_id>.if, but I quickly got lost in the syntax.

humitos commented 3 months ago

Thanks for your feedback! This is looks a good use case to support.

I'm adding this issue to the roadmap to see if we can prioritize it in any of the following sprints. It's worth to mention also that I don't know how to do it and I will need to research as well 😅 -- receiving a PR would be awesome 👍🏼

stevepiercy commented 3 months ago

Thanks for adding it to the roadmap.

I'd be happy to test a PR. I lack familiarity with GitHub workflow language and syntax to offer much, but I'm open to learn.

In my referenced PRs from plone/volto, which I closed after my failed attempts, you can see my control and test processes. I also pushed commits to the main branch of the plone/volto repo (which we rarely do, except when testing CI) with some of my failed attempts. See https://github.com/plone/volto/commit/938ae3520728ae6bee451d1bdba378aa18d3ee93. It was worth a shot, but failed due to incorrect syntax.

The if syntax is not too difficult to comprehend, but I got lost with converting an array of filepaths in yaml to its one-line syntax.