Move to single directory and auto generate/publish docs

[sjsrey]

Currently we build the html docs out of docsrc and use a sync script to copy over to docs and publish via gh-pages:

It would be great to refactor this to use the gh-pages branch approach to publish and build out of a single directory.

I'm assuming this would enable the bot action to work as intended.

[jGaboardi]

I can see that this action is running, but where is it running from? The workflow is not showing up in the .github/workflows/ directory:

[jGaboardi]

Ahhh maybe because I don't have access to Settings.

[sjsrey]

Yup, that is the mystery.

[sjsrey]

I'm seeing the same thing you are:

[sjsrey]

https://github.blog/changelog/2021-12-16-github-pages-using-github-actions-for-builds-and-deployments-for-public-repositories/

[jGaboardi]

In spaghetti I have access to Settings/Pages, but not for PySAL. Do you see something like this?

[jGaboardi]

Let's @knaaptime and @martinfleis in on this for potential insight.

[sjsrey]

yes, see the top of this issue.

[sjsrey]

I think the reason the docs were not getting updated (2.4 was the last version) is that I forgot to run the sync step last release. I just did a pr that has the sync #1247 which should update now.

But moving forward it would be nice to move away from this two-step docsrc -> docs dance.

[knaaptime]

But moving forward it would be nice to move away from this two-step docsrc -> docs dance.

we solved this in the other packages, so this is a straightforward fix

[sjsrey]

The other complication I want to address is that with the move to versioneer, I'm not quite sure how to have the right tag on the docs when we build them. This is probably another good reason to automate the doc build.

[knaaptime]

I'm not quite sure how to have the right tag on the docs when we build them.

martin might have some insight. Ive seen this raised over in geopandas too

[sjsrey]

the release is ready to go, but I wanted to see if we could dial in the doc build as part of the release. Ideally, we want to be able to update the docs if needed, but have the tag match the release tag.

[martinfleis]

The other complication I want to address is that with the move to versioneer, I'm not quite sure how to have the right tag on the docs when we build them.

Tag the repository and run sphinx. That way you get a proper version on the docs. No commit in between.

[sjsrey]

This is the problem with the current approach:

[martinfleis]

Yeah, because in the branch you are using, the latest tag is 2.2.0. And then there's 215 commits after that.

[sjsrey]

I have a draft release on gh that will create the v2.6.0 tag when published.

[sjsrey]

So if I publish the release, I can then update the docs and it should grab the new tag?

[martinfleis]

So if I publish the release, I can then update the docs and it should grab the new tag?

Yes, that is the theory and my experience. We can always fix docs later if that won't work as expected.

[sjsrey]

release action appears to work for pypi

[sjsrey]

Will have to fix the version tag before pushing to pypi in that action:

Version is 2.6 but our badge in the description is 2.5.

[martinfleis]

Version is 2.6 but our badge in the description is 2.5.

Try reloading, I see 2.6.0

[jGaboardi]

Might be another chance to look into #1216?

[sjsrey]

Once #1252 is merged, the remaining thing (I think) here is to add this gh-action.