Modern CI and Python Tooling

[svenevs]

Sorry for this falling off my radar. Per our original discussion goals:

• Create GitHub actions CI.
• Test changes to packaging via setup.py (cherry-picked relevant changes from @althonos, closes Update tooling and add CI configuration #203)
• Add placeholder tests for linting (to be added later)
  • Some linting is there. There's like no actual python code though haha.
  • The "test" is just running sphinx-build --version.
• Make sure that demo site builds in CI.
  • Warnings and nitpicky. Note: see changes to examples.rst, there seems to be a major problem with the sphinx javascript domain and linking parameters. Just switched to C++ instead...not our problem. AKA prefer nitpicky / warnings=error over sample js code.
• Make sure we have local demo-server.
• Push things to gh-pages branch only on tagged releases.
• Update contributing section of README to explain how to use the new tools.
• Remove old tooling such as fabfile, top-level makefile, and outdated section in README.
• Fixes Incompatible with newer setuptools (>=58.0.0) due to use of 2to3 in setup.py #216.

CC: @jorisvandenbossche ref: #201

[ryan-roemer]

Everything looks great so far! Fantastic work @svenevs !

[svenevs]

@ryan-roemer we should use TestPyPI, can you please

1. Create an account at test.pypi.org if you haven't already.
2. Claim the sphinx-bootstrap-theme there (currently unclaimed!)
3. Go to account settings on TestPyPI and "Add API Token".
4. Add it as a test_pypi_password secret (further explanation / why doing this here) to this repo?

I'm looking into generative numbering schemes at the moment, want to see what we can do for deployment on TestPyPI first 🙂 If it works as we expect it to, then we'll ultimately need to redo steps 3 and 4 for the real PyPI and save it in a different secret pypi_password.

[ryan-roemer]

@svenevs -- I created an account. Do you have a tl;dr on claiming the package name? I don't see the way to do it easily from the packages page in my account? Thanks!

[svenevs]

Hehe ... I couldn't figure it out either, but apparently if you just try and upload a package then you get to claim it. I did this, and added you as owner collaborator there. Will start playing with TestPyPI uploads via CI now :)

[svenevs]

@ryan-roemer sorry for all the spam, it's actually very difficult to obtain the commit message via GitHub actions. Now that you are a maintainer on Test PyPI, can you complete steps 3 and 4 here? #206 (comment)

I want to make sure the uploads work as we expect, and then propose an alternative approach to tracking version numbers in __init__.py.

[ryan-roemer]

@svenevs -- Thanks for your continued work! I generated a token scoped to this package and added it to secrets in this repo as test_pypi_password. Let me know how it goes!

[ryan-roemer]

Tested out tox -e server and worked great!

[althonos]

Any update on this ? 😉

[svenevs]

@ryan-roemer I'm so sorry, this completely fell through the cracks (I went into open source shutdown...). I've added instructions, please review the revised contributing section as well as the packaging section beneath it to make sure you understand how things work here. My recollection is you wanted help here getting the python stuff updated, this should be a good release setup for you but if anything doesn't make sense please ask! Link to read rendered rst:

https://github.com/ryan-roemer/sphinx-bootstrap-theme/tree/feat/modern-ci-py-tooling#contributing

Doing anything fancy with commit messages for Test PyPI is an exercise in futility, or at least I don't like it and don't intend to finish that work. I'm going to check back in on this tomorrow, I was able to upload a new version to Test PyPI, specifically 0.8.0.dev1, but it's not showing up online edit it's there. There are other issues I'm experiencing with that website, but I think it's some kind of outage that will self resolve? Try bumping the dev version following the instructions and see if you can upload there.

Some followups here before merging:

1. The "test" is the same as "docs", but really it's just there to make sure that for a given version of sphinx and python things actually install and build. I haven't really looked into if this is actually testing anything. But it seems to be a valid "test"?

   sphinx-bootstrap-theme/tox.ini

   Line 7 in f6256f7

   [testenv]

2. The linkcheck test fails because I don't know what the goal is with this hyperlink. Can we just remove it? In file example.rst the link to view the `source <./_sources/examples.txt>`_ of this page to see the specific.

3. An email is required for uploads. Do you want to update this? (It can stay as is, I use a junk email on my uploads... spammy robot crawlers and all).

   sphinx-bootstrap-theme/setup.cfg

   Line 5 in 389ff91

   author-email = [email protected]

[ryan-roemer]

Hi @svenevs

Thanks so much for picking this up! I've done a final re-review and AFAICT we're all good and ready to get this merged soon.

For your questions:

1. Sounds fine.
2. Yeah, go ahead and remove that whole sentence around the link
3. I'm fine with that same email in place (as it's been there for a long time so far anyways). But thanks for the consideration!

From here, once linkcheck works and CI's all green please go ahead and do the full merge (I usually do squash and merge by preference, but it's totally up to you) and let's see how everything goes!

And from there, maybe we next push a tag and see if we can do a "real" release!

[svenevs]

I usually do squash and merge by preference, but it's totally up to you) and let's see how everything goes!

Squash merge FTW, especially with all the garbage commits above hehe.

• The good news: GitHub Pages deployment was successful, it's live right now (see bottom with the new instructions added here).
• The bad news: ${{ secrets.pypi_password }} is invalid, see build log here. I can't fix that.
  • Error message: Warning: It looks like you are trying to use an API token to authenticate in the package index and your token value does not start with "pypi-" as it typically should. This may cause an authentication error. Please verify that you have copied your token properly if such an error occurs.
  • You can also, since we've abandoned it, delete the secrets.test_pypi_password if it is in there. I forget, I can't edit the secret store.
  • After setting the proper pypi_password token in the Settings tab on this repo, delete the 0.8.0 tag and re-push it to redeploy 🙂
    • git tag -d v0.8.0 and git push --delete origin v0.8.0, then git tag v0.8.0 and git push --tags.
    • Then do the dev version bump, usually for those I just set __version__ = "0.8.1.dev0" and commit directly to master with a message along the lines of v0.8.1 dev version bump.

SO CLOSE! hehe.

[svenevs]

Oh, since redploy is going to happen, before you re git tag v0.8.0 you will probably want to remove the v0.8.0 commit from the gh-pages branch.

# get rid of the otherwise to be duplicated v0.8.0 build
$ git checkout gh-pages
$ git reset --hard HEAD~1
$ git push -f

# now tag and redploy after setting pypi_password
$ git checkout master
$ git tag v0.8.0
$ git push --tags

This is so exciting 🙃

[ryan-roemer]

@svenevs Haha, I never got around to setting pypi_password. Should that be lower or uppercase?

I'll try to get to all the remaining work you have above this weekend or Monday if I get overloaded with kid wrangling...

[svenevs]

Oh hehehehe ok. For the most part just follow the instructions here: https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#saving-credentials-on-github

But in our case, it needs to be saved in the secret store as pypi_password so that this code uses it 🙂

sphinx-bootstrap-theme/.github/workflows/package.yaml

Line 26 in be04b92

password: ${{ secrets.pypi_password }}

I can do the redeployment if you prefer, just need the token password from you first.

[althonos]

Happy to see this merged, congrats for the good work!

[ryan-roemer]

Looks like we were successful!!! (?)

• https://github.com/ryan-roemer/sphinx-bootstrap-theme/runs/3577773001
• https://pypi.org/project/sphinx-bootstrap-theme/
• https://ryan-roemer.github.io/sphinx-bootstrap-theme/README.html

[jkwmoore]

Thanks for sorting this fellas!