Show not-yet-released change notes in Sphinx docs #2650
Conversation
webknjaz
changed the title
docs/conf.py
Outdated
| PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve() | ||
| get_scm_version = partial(get_version, root=PROJECT_ROOT_DIR) | ||
|
|
||
| # The short X.Y version | ||
| version = '.'.join( | ||
| get_scm_version( | ||
| local_scheme='no-local-version', | ||
| ).split('.')[:3], | ||
| ) | ||
|
|
||
| # The full version, including alpha/beta/rc tags | ||
| release = get_scm_version() |
There was a problem hiding this comment.
This logic is redundant and conflicts with the work done by jaraco.packaging.sphinx. Is it needed?
There was a problem hiding this comment.
It's needed because otherwise jaraco.packaging.sphinx selects the hardcoded version of setuptools which is something that's already been released while this match makes it the next guess provided by setuptools-scm.
If I remove this, the changelog would look like:
# v56
- entries that are still in the form of fragments
# v56
- entries you've generated on release
but the goal of this change is to have something like
# v57.dev0
- entries that are still in the form of fragments
# v56
- entries you've generated on release
So that next version preview should either be generated here in sphinx or you should modify your release flow to change the hardcoded version to v57.dev0 right after the release.
Here's what it looks like:
There was a problem hiding this comment.
Here's the PR build for preview: https://setuptools--2650.org.readthedocs.build/en/2650/history.html
There was a problem hiding this comment.
I would actually like to get this project enabled with setuptools_scm, but until the project itself can adopt setuptools_scm, it seems a bad idea to paper over the issue that setup.py --version is reporting an incorrect version by partially adopting setuptools_scm but only in docs.
Currently, setuptools defines egg_info.tag_build and egg_info.tag_date to provide a post-release tag. I'm a little surprised that setup.py --version (what jaraco.packaging currently uses to elicit the version) doesn't include that tag. That's probably another bug.
Regardless, jaraco.packaging should probably invoke PEP 517 to get the package metadata and the version from that. Doing so would have the unfortunate side-effect of rendering the .post and date even for tagged commits (which are only disabled when cutting a release).
Since adopting setuptools_scm for this project would solve all of these problems, I'd like to first tackle that issue (#2656).
There was a problem hiding this comment.
Alright, I'll change the approach a bit and will just remove the version from this title, for the time being, it's not that important. We can re-add it later, once #2656 is in.
|
Can you please provide an explanation of what the issue is? Where does towncrier make |
Yes, you are right. I'll make a separate PR. Towncrier's own changelog is not very explicit about this but the old version (before 19.9) used to prepend the title outside the template and starting 19.9+ it just relies for the variable to be present inside of it. |
webknjaz
force-pushed
the
docs/towncrier-upgrade
branch
from
16d337c to
f7f0e95
Compare
|
I've filed that patch as #2654 but also kept the corresponding commit in this branch as a base. |
webknjaz
force-pushed
the
docs/towncrier-upgrade
branch
from
f7f0e95 to
3ac9894
Compare
webknjaz
force-pushed
the
docs/towncrier-upgrade
branch
from
3ac9894 to
b769487
Compare
webknjaz
force-pushed
the
docs/towncrier-upgrade
branch
from
b769487 to
cff5e45
Compare
|
@jaraco looks like we've found a side-effect of having non-integrated packaging-related deps in envs with tests... Any ideas? |
webknjaz
force-pushed
the
docs/towncrier-upgrade
branch
from
cff5e45 to
36da400
Compare
webknjaz
force-pushed
the
docs/towncrier-upgrade
branch
2 times, most recently
from
464aa59 to
3329a7e
Compare
|
@jaraco I dropped setuptools-scm from this PR, it should be good to go now: https://setuptools--2650.org.readthedocs.build/en/2650/history.html. |
webknjaz
force-pushed
the
docs/towncrier-upgrade
branch
from
3329a7e to
5bb4299
Compare
|
@jaraco I rebased this to fix the conflicts. |
docs/conf.py
Outdated
| # -- Options for towncrier_draft extension -------------------------------------------- | ||
|
|
||
| PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve() | ||
|
|
||
| towncrier_draft_autoversion_mode = "draft" # or: 'sphinx-release', 'sphinx-version' | ||
| towncrier_draft_include_empty = True | ||
| towncrier_draft_working_directory = PROJECT_ROOT_DIR | ||
| # Not yet supported: towncrier_draft_config_path = 'pyproject.toml' # relative to cwd |
There was a problem hiding this comment.
I'm annoyed that towncrier_draft requires all of these settings. Why aren't the defaults good enough?
There was a problem hiding this comment.
Yeah, I just didn't want to assume the working directory because cwd may depend on what you set in changedir in tox.ini effectively making this setup extremely fragile when the setting there is changed because the connection is highly unobvious. I guess I could attempt implementing some sort of an autodetection on the extension side but for now, it only implements a bare minimum w/o making assumptions.
Essentially, if I were to look into the config and see .., I'd assume it's relative to the dir with conf.py but it's relative to the process' current working directory.
|
I'm a little meh on this change. Setuptools aims to do frequent releases, so the benefit of generating changelog entries for yet unreleased changes is of little value for that uncommon scenario. I'm not necessarily opposed to it as long as it doesn't add a lot of debt to the project. The fact that it has to hard-code the path to the project and specify a whole selection of settings feels a little cumbersome to me. I'd be much more inclined to accept this change if enabling the extension and adding the directive was all that was needed. |
|
This latest change is much cleaner. I can live with this... as long as it looks okay during a release. |
|
I'm sad to report that towncrier_draft still generates the content even when there's nothing to report, so here's what the official release docs look like:
That's ugly. I'm going to undo the merge. |
|
I've force pushed 317ad2c to main, effectively removing the merge commit 99cabc2, and opening up the prospect of re-submitting fef727f as a new PR, but honestly, I wouldn't bother. The value proposition is small and the trouble seems to be non-trivial. Still, I won't prescribe. I'll accept a clean, concise application of this technique that doesn't clutter the official docs. |
|
I believe with |
I confirmed this is the case. Sure would be nice if this behavior were the default. I'll be submitting a new PR shortly. |
IIRC we've hit some corner case with this in the pip docs: pypa/pip#9505. |
Summary of changes
The recent towncrier release now requires a
{{ top_line }}variable in the template (as discovered in pypa/pip#9815). Without this change, the changelog updates will have no title when the new Towncrier is used and this will happen sooner or later because it's unpinned in the deps.Also, besides fixing that problem above this change integrates an extension for showing the upcoming release change notes in the Sphinx docs whenever standalone fragments are present in the tree.
Blocked by: #2651.
Pull Request Checklist
changelog.d/.(See documentation for details)
Ref: pypa/pip#9815