Bumping documentation

[charlesbluca]

With the major refactor to pangeo-forge pending, it would be timely to update the documentation to adequately represent the direction it is going in. This should include:

• Definition of what Executors, Pipelines, and Recipes are
  • Basic functionality of Recipes such as prepare(), cache_input(), store_chunk(), ...
• Tutorials on how to make and submit a recipe
• Information on how to extend pangeo-forge with new Recipe classes

It might be useful to consider what info we consider more fitting for the landing page as we begin to populate that. Since the docs are published through Read The Docs, I think we should probably add some additional maintainers to our project there, since currently the only one is @TomAugspurger.

[TomAugspurger]

Happy to add others there, if you could post your RTD username.

[charlesbluca]

Sure, my username is same as here - charlesbluca.

[TomAugspurger]

Invite sent.

…

On Jan 18, 2021, at 3:36 PM, Charles Blackmon-Luca ***@***.***> wrote: Sure, my username is same as here - charlesbluca. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#28 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKAOIQOU5ZY5ZWNXMXKTI3S2SSXNANCNFSM4WHZOMIA>.

[charlesbluca]

Thanks! I'll let you know if I have any other questions about the settings on RTD.

[charlesbluca]

As part of this process, I have added a simple workflow to generate previews of the documentation in response to PRs.

Since this workflow creates new (preview) branches whenever a local PR is made affecting docs/, I would also like to modify main.yaml so that only pushes to the master branch will trigger CI, as currently it would also be running unnecessarily on preview branches.

[rabernat]

What are the pros and cons of using our own workflow vs. the RTD github action to generate previews? cc @jbusecke

[jbusecke]

I dont have any experience with rolling docs preview manually, but from my experience, RTD can be quite slow (often being the last item of CI that finishes). If this approach is faster, I think that would be a really nice addition!
The downside (I guess) might be that the preview might not use the exact same dependencies and could potentially be slightly different from the final one built on RTD?

[charlesbluca]

If the rolling docs feature is essentially the same as my workflow (giving previews of what documentation would look like after a PR), then I'm happy to use that instead!

My workflow is still pretty hacked together, so there are plenty of cons to look out for:

• Populating the repo with -preview branches to be deleted later
• Resulting in unexpected behavior if we create branches ending in -preview
• Giving motivation to change our main CI in the first place

Is there documentation anywhere on RTD's preview functionality?

[jbusecke]

https://docs.readthedocs.io/en/stable/guides/autobuild-docs-for-pull-requests.html

[charlesbluca]

Thanks! I'll play around with this for now and see how well it performs compared to the workflow.

[jbusecke]

Awesome. Let me know what you find out. Very curious about this.

[charlesbluca]

Opened up a PR #32 to test out autobuild, but it doesn't seem to show RTD in the checks - according to the troubleshooting section, it looks like this might be because RTD isn't authorized as an app in this organization, or the webhooks need to be reconfigured? I'll look into that, but if an org owner could confirm whether or not RTD is authorized that would be great.

[jbusecke]

I had a similar issue in another repo. @rabernat was both the owner and able to figure it out. So maybe he can provide some input?

[TomAugspurger]

@charlesbluca can you try pushing another commit. I may have just authorized RTD's oauth application for pangeo-forge. Not 100% sure though.

[rabernat]

I got a notification that RTD was authorized for this repo.

[charlesbluca]

Sure! I'll push another commit to my PR and see if it works out.

[charlesbluca]

It looks like we still aren't getting RTD checks showing. On top of that, it looks like the docs build failed upon merging Ryan's big PR, though we still don't have any indication of why. 😕

If the OAuth is authorized, it could be an issue with the webhook set up on RTD's side - maybe resyncing it could fix things?

[charlesbluca]

@rabernat @jhamman I added you both as maintainers on RTD - this should make the build failures more accessible for the time being while we sort out these checks.

[cisaacstern]

RTD works, thanks to these early efforts! Closing.