Reviewing documentation

[genedan]

I've been wondering what the best way to review contributions to the docs are. I've defaulted to checking out people's branches and then building them myself to take a look. Another idea is looking at branches on RTD, although that would be a steep expectation to place on outside contributors.

The way Pandas does it is that there is a workflow that uploads an artifact of the build:

Once, the pull request is submitted, GitHub Actions will automatically build the documentation. To view the built site:

    Wait for the CI / Web and docs check to complete.

    Click Details next to it.

    From the Artifacts drop-down, click docs or website to download the site as a ZIP file.

[kennethshsu]

This would be great! Right now we have the experimental branch, which is not protected, and then if two doc changes are waiting to be reviewed they will collide in there.

[henrydingliu]

i prefer the rtd approach, particularly since we haven't resolved #976. there's also information in the rtd build log that we don't get through github action, see #1111.

[kennethshsu]

@henrydingliu can you clarify what you mean by you prefer the RTD approach? As in build out a new doc site for review instead of using automated action here that generates a doc site as static file?

The RTD approach is most reliable, but it takes quite a bit of time to setup, especially if you aren't an admin. You would have to spin up your own instance and generate the site. We could setup multiple "experimentals" though, but that will make it so hard to manage and it would be honestly a bit ugly...

[henrydingliu]

sorry for not specifying, by "RTD approach", i meant either experimental versions on the main docsite or setting up personal docsites. it does take a bit to setup. but once it's setup, it's automatically built upon commit, which would be equally convenient for the PR raiser and slightly more convenient for the reviewer (don't have to download and extract a zip).

I've defaulted to checking out people's branches and then building them myself to take a look

I do that too sometimes! I merge it into the experimental branch on my fork, which has its own version on my rtd site.

to be clear, i'm not opposed to the zip upload approach. for now the blocker is the uv vs pip dependency difference, which has been kicking our ass once every couple of weeks in the last quarter.

[henrydingliu]

loving the new rtd with each PR approach. good to close?

[kennethshsu]

You mean good to close the experimental branch? I think I will kill the RTC render first and we can keep the branch alive until everything is picked up or merged. But ya with the docs build this way there's no need for experimental anymore.

[henrydingliu]

i meant good to close this discussion.

commits to experimental are all merged in except for chapter 10 which is already in a separate PR

[kennethshsu]

That's #1180 right? Ok we can kill the branch too then.