Closed canepan closed 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).
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.
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)rst2html.py
(from docutils, I believe) to produce a file I open with my browser, but it isn't ideal