search

jaraco / skeleton

A generic project skeleton for Python projects.
http://blog.jaraco.com/skeleton/
MIT License
121 stars 36 forks source link

Documentation about workflows and publishing automation #69

Closed canepan closed 1 year ago

canepan commented 1 year ago

Hi @jaraco I recently created a project I would like to be more serious than my previous attempts, and thus I searched for a "standard" structure for it to be published to github and pypi. I stumbled this repo, and I think it's a very solid option for it.

While using it, though, I found little documentation beyond the initial blog post, so I have some questions.

  1. Is there a doc site I can use instead of creating an issue for trivial questions (readthedocs is empty, maybe because some workflow is failing?
  2. What is the expected workflow to publish a package to pypi? I tried tox -e release, which creates the local packages (with and without TWINE_PASSWORD set), but then I have to upload them manually (I also have my pypi token in ~/.pypirc)
  3. Is there an easy way to verify/check the output produced for the rst docs before pushing them? Currently I am using rst2html.py (from docutils, I believe) to produce a file I open with my browser, but it isn't ideal
jaraco commented 1 year ago

Hi @jaraco I recently created a project I would like to be more serious than my previous attempts, and thus I searched for a "standard" structure for it to be published to github and pypi. I stumbled this repo, and I think it's a very solid option for it.

Fantastic. Welcome.

While using it, though, I found little documentation beyond the initial blog post, so I have some questions.

Actually, although that link is hosted under blog.jaraco.com, it's actually the documentation for the skeleton (as linked by the skeleton badge). That documentation is maintained and hosted under the gh-pages branch of this repo. Unfortunately, I'm not aware of a way to use a different hostname (I've tried and ran into issues with Github pages assumptions).

1. Is there a doc site I can use instead of creating an issue for trivial questions (readthedocs is empty, maybe because [some workflow is failing](https://readthedocs.org/projects/skeleton/badge/?version=latest)?

I don't use doc sites for questions. For that, I rely on Github issues. The link you've found there is a template link. It's meant for the user to replace downstream (if they choose to enable RTD). I've been meaning to replace skeleton with a more obvious field like PROJECT to make it more obvious which fields are meant to be substituted.

2. What is the expected workflow to publish a package to pypi?
   I tried `tox -e release`, which creates the local packages (with and without TWINE_PASSWORD set), but then I have to upload them manually (I also have my pypi token in ~/.pypirc)

You shouldn't have to run tox -e release manually. It should happen automatically for tagged commits. And that definitely should cause twine to upload the assets. You can run tox -e release manually if the automation isn't working.

For the automated releases to work, you do need to configure the PYPI_TOKEN in the Github Settings Secrets Actions (mapped here).

You probably don't want to store your token in plaintext. I'd suggest storing it using twine's keyring support. Just remember that the "username" is __token__ for token-based operations.

3. Is there an easy way to verify/check the output produced for the rst docs before pushing them?
   Currently I am using `rst2html.py` (from docutils, I believe) to produce a file I open with my browser, but it isn't ideal

If you're using jaraco.skeleton, it automatically checks the README.rst for validity via pytest-checkdocs. For other stuff in docs/, you can run tox -e docs, which will generate the docs to build/html after which I'll often open build/html/index.html (open is a macOS detail; use start on Windows and your expertise on Linux).