Add support for pushing PR previews to a different branch and/or different repo #1307

DilumAluthge · 2020-05-02T01:27:31Z

Currently, the only way to have PR previews is to put them in the previews/PRXX subdirectory in the same branch of the same repository as your actual docs. For example, if your actual docs are pushed to the gh-pages branch of the MyPackage.jl repo, then the PR preview for PR number 123 is pushed to the previews/PR123 subdirectory in the gh-pages branch of the MyPackage.jl repo.

But, for a variety of reasons, you may not want to keep your PR previews in the same branch and/or repo as your actual docs.

This PR adds the ability to customize the branch and/or repo to which PR previews are pushed. The options are:

Same repo, same branch - Prior to this PR, this is the only option. In this PR, we keep it as the default behavior.
Same repo, different branch
Different repo, same branch name
Different repo, different branch name

We also add support for the DOCUMENTER_KEY_PREVIEWS environment variable. If the DOCUMENTER_KEY_PREVIEWS environment variable is set, then that will be the SSH key that is used for pushing PR previews. If the DOCUMENTER_KEY_PREVIEWS environment variable, then the regular DOCUMENTER_KEY environment variable will be used.

Example

Pull request: Add a brief introductory sentence JuliaHealth/HealthBase.jl#7
Preview: https://juliahealth.org/HealthBase.jl-previews/previews/PR7/
Repo to which previews are pushed: https://github.com/JuliaHealth/HealthBase.jl-previews/tree/gh-pages/previews

Prior art

This is quite easy with Franklin. See e.g. my setup here:

Workflow file: https://github.com/JuliaHealth/juliahealth.github.io/blob/dev/.github/workflows/deploy.yml
Repo to which previews are pushed: https://github.com/JuliaHealth/juliahealth.github.io-previews/tree/gh-pages/previews

DilumAluthge · 2020-05-02T02:52:38Z

This is ready for review @mortenpi @fredrikekre

…erent repo

DilumAluthge · 2020-05-02T21:22:51Z

Bump @mortenpi

mortenpi · 2020-05-02T21:28:52Z

I haven't gone through the code in detail yet but glancing at it, it looks good! Will try to go through this within the next few days.

Could you also add a note into CHANGELOG.md?

DilumAluthge · 2020-05-03T07:35:16Z

Could you also add a note into CHANGELOG.md?

Done!

Let me know if the changelog entry is too verbose.

mortenpi

LGTM as is!

One tiny request: could we have a test in test/deployconfig.jl that makes sure that DOCUMENTER_KEY_PREVIEWS gets properly fetched from the environment too (and gets ignored when it is in the env. but it's not a preview build)? That's the only thing that I saw that wasn't being tested at the moment.

src/deployconfig.jl

Co-authored-by: Morten Piibeleht <morten.piibeleht@gmail.com>

DilumAluthge · 2020-05-04T01:11:45Z

One tiny request: could we have a test in test/deployconfig.jl that makes sure that DOCUMENTER_KEY_PREVIEWS gets properly fetched from the environment too

This part is done.

(and gets ignored when it is in the env. but it's not a preview build)

This will be hard. The logic for this part is in the git_push function, so to test it we'd need to have some kind of integration test harness.

mortenpi · 2020-05-04T02:50:31Z

(and gets ignored when it is in the env. but it's not a preview build)

This will be hard. The logic for this part is in the git_push function, so to test it we'd need to have some kind of integration test harness.

Ah, that's right, I didn't look at it closely enough. In that case, I'd say it's good to go. Thanks for the contribution!

For planning purposes: would it be fine for you to use Documenter master for a while? I would definitely like to have this in a minor release, but there are a few other things I would like to get into 0.25, so it might be a few weeks before a release.

fredrikekre · 2020-05-04T06:47:19Z

src/Documenter.jl

@@ -461,13 +484,14 @@ function deploydocs(;
                @debug "running extra build steps."
                make()
            end
-            @debug "pushing new documentation to remote: '$repo:$branch'."
+            @debug "pushing new documentation to remote: '$deploy_branch:$branch'."


deploy_repo?

Yeah good call

Also :$deploy_branch?

DilumAluthge · 2020-05-04T07:15:47Z

For planning purposes: would it be fine for you to use Documenter master for a while? I would definitely like to have this in a minor release, but there are a few other things I would like to get into 0.25, so it might be a few weeks before a release.

Sounds good! If you remember, just ping me whenever you make the release, so that I can remember to switch from using Documenter master to using Documenter 0.25.

fredrikekre · 2020-05-04T08:10:46Z

The docs for how this interface should be used also needs to be updated.

mortenpi · 2020-05-04T23:09:01Z

The fallbacks for deploy_folder here should also return DeployDecision -- currently deploydocs throws an error.

@fredrikekre, I guess the related docstring is the one you mean that should get updated?

fredrikekre · 2020-05-04T23:13:17Z

Yes.

DilumAluthge · 2020-05-05T17:27:38Z

#1315

Add support for pushing PR previews to a different branch and/or diff…

e938a82

…erent repo

mortenpi added the Type: Enhancement label May 2, 2020

mortenpi added this to the 0.25.0 milestone May 2, 2020

Add a changelog entry

e81a8b2

DilumAluthge closed this May 3, 2020

DilumAluthge reopened this May 3, 2020

mortenpi reviewed May 4, 2020

View reviewed changes

src/deployconfig.jl Outdated Show resolved Hide resolved

DilumAluthge and others added 2 commits May 3, 2020 20:52

Update src/deployconfig.jl

796d40e

Co-authored-by: Morten Piibeleht <morten.piibeleht@gmail.com>

Add a test for DOCUMENTER_KEY_PREVIEWS

a9ee67c

mortenpi merged commit 51c2b29 into JuliaDocs:master May 4, 2020

DilumAluthge deleted the dpa/previews-repo-branch branch May 4, 2020 03:03

fredrikekre reviewed May 4, 2020

View reviewed changes

DilumAluthge mentioned this pull request May 4, 2020

Fix a typo in a debug statement; also add missing PR links to changelog #1310

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add support for pushing PR previews to a different branch and/or different repo #1307

Add support for pushing PR previews to a different branch and/or different repo #1307

DilumAluthge commented May 2, 2020 •

edited

Loading

DilumAluthge commented May 2, 2020

DilumAluthge commented May 2, 2020

mortenpi commented May 2, 2020

DilumAluthge commented May 3, 2020

mortenpi left a comment

DilumAluthge commented May 4, 2020

mortenpi commented May 4, 2020

fredrikekre May 4, 2020

DilumAluthge May 4, 2020

mortenpi May 4, 2020

DilumAluthge May 4, 2020

DilumAluthge commented May 4, 2020 •

edited

Loading

fredrikekre commented May 4, 2020

mortenpi commented May 4, 2020

fredrikekre commented May 4, 2020

DilumAluthge commented May 5, 2020

Add support for pushing PR previews to a different branch and/or different repo #1307

Add support for pushing PR previews to a different branch and/or different repo #1307

Conversation

DilumAluthge commented May 2, 2020 • edited Loading

Example

Prior art

DilumAluthge commented May 2, 2020

DilumAluthge commented May 2, 2020

mortenpi commented May 2, 2020

DilumAluthge commented May 3, 2020

mortenpi left a comment

Choose a reason for hiding this comment

DilumAluthge commented May 4, 2020

mortenpi commented May 4, 2020

fredrikekre May 4, 2020

Choose a reason for hiding this comment

DilumAluthge May 4, 2020

Choose a reason for hiding this comment

mortenpi May 4, 2020

Choose a reason for hiding this comment

DilumAluthge May 4, 2020

Choose a reason for hiding this comment

DilumAluthge commented May 4, 2020 • edited Loading

fredrikekre commented May 4, 2020

mortenpi commented May 4, 2020

fredrikekre commented May 4, 2020

DilumAluthge commented May 5, 2020

DilumAluthge commented May 2, 2020 •

edited

Loading

DilumAluthge commented May 4, 2020 •

edited

Loading