Integrate towncrier changelog draft sphinx ext #1640
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
webknjaz
requested review from
asottile,
gaborbernat and
obestwalter
as code owners
|
(no change note because it's not public-facing) |
webknjaz
force-pushed
the
docs/towncrier-changelog-draft-sphinx-ext
branch
from
204fcec to
4664a30
Compare
webknjaz
commented
Jul 31, 2020
Comment on lines
-27
to
-32
| for pattern, replacement in ( | ||
| (r"[^`]@([^,\s]+)", r"`@\1 <{}/\1>`_".format(home)), | ||
| (r"[^`]#([\d]+)", r"`#pr\1 <{}/\1>`_".format(issue)), | ||
| ): | ||
| for path in fragments_path.glob("*.rst"): | ||
| path.write_text(re.sub(pattern, replacement, path.read_text())) |
There was a problem hiding this comment.
@gaborbernat is this really necessary?
webknjaz
commented
Jul 31, 2020
| if "No significant changes" in changelog: | ||
| content = "" | ||
| else: | ||
| note = "*Changes in master, but not released yet are under the draft section*." |
There was a problem hiding this comment.
@gaborbernat the only difference is that the extension does not implement this (I simply missed it). Is it vital if this line is missing?
This change implements injecting the Towncrier draft change notes RST output into the Sphinx-managed docs site. It is heavily inspired by the work of @gaborbernat in tox and reinvented as a native Sphinx extension. Refs: * tox-dev#859 * ansible/pylibssh@f5f9ef1 In internally generates an unreleased changelog for the next unpublished project version (by calling `towncrier` in a subprocess) and provides it for injection as an RST directive called "towncrier-draft-entries". To start using it, first, add it to extensions in `conf.py`: extensions.append('towncrier_draft_ext') Then, optionally, set the global extensions options: towncrier_draft_autoversion_mode = 'scm-draft' # or: 'scm', 'draft', 'sphinx-version', 'sphinx-release' towncrier_draft_include_empty = True towncrier_draft_working_directory = PROJECT_ROOT_DIR towncrier_draft_config_path = 'pyproject.toml' # relative to cwd Their meaning is as follows: * towncrier_draft_autoversion_mode -- mechanism for the fallback version detection. It kicks in if, when using the directive, you don't specify the version argument and then will be passed to the `towncrier` invocation. Possible values are: * 'scm-draft' -- default, use setuptools-scm followed by a string "[UNRELEASED DRAFT]" * 'scm' -- use setuptools-scm * 'draft' -- use just a string "[UNRELEASED DRAFT]" * 'sphinx-version' -- use value of the "version" var in as set in `conf.py` * 'sphinx-release' -- use value of the "release" var in as set in `conf.py` * towncrier_draft_include_empty -- control whether the directive injects anything if there's no fragments in the repo. Boolean, defaults to `True`. * towncrier_draft_working_directory -- if set, this will be the current working directory of the `towncrier` invocation. * towncrier_draft_config_path -- path of the custom config to use for the invocation. Should be relative to the working directory. Not yet supported: the corresponding Towncrier CLI option is in their master but is not yet released. Don't use it unless you install a bleading-edge towncrier copy (or they make a release). Finally, use the directive in your RST source as follows: .. towncrier-draft-entries:: |release| [UNRELEASED DRAFT] The inline argument of the directive is what is passed to towncrier as a target version. It is optional and if not set, the fallback from the global config will be used. Pro tip: you can use RST substitutions like `|release|` or `|version|` in order to match the version with what's set in Sphinx and other release-related configs. src: https://github.com/ansible/pylibssh/blob/8b21ad7/docs/_ext/towncrier_draft_ext.py Resolves tox-dev#1639
webknjaz
force-pushed
the
docs/towncrier-changelog-draft-sphinx-ext
branch
from
4664a30 to
95eea48
Compare
gaborbernat
requested changes
Jul 31, 2020
webknjaz
commented
Jul 31, 2020
| @@ -7,7 +7,7 @@ Versions follow `Semantic Versioning <https://semver.org/>`_ (``<major>.<minor>. | |||
| Backward incompatible (breaking) changes will only be introduced in major versions | |||
| with advance notice in the **Deprecations** section of releases. | |||
|
|
|||
| .. include:: _draft.rst | |||
| .. towncrier-draft-entries:: DRAFT | |||
There was a problem hiding this comment.
@gaborbernat DRAFT here is a string argument that is passed to towncrier --draft --version '{THIS VALUE}'. It can be anything. For example, it could be |release| (EXPLANATION THAT IT'S A DRAFT) and then it'd be rendered like 3.88.99 (EXPLANATION THAT IT'S A DRAFT).
I tried to keep the behavior as it is now but you have options FYI.
|
Ah, okay. Release will take a while. But at least you could preview it and see if anything is missing. |
|
@webknjaz When you make the first PR for the release just tag me to review 👍 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This change vendors the sphinx extension from https://github.com/ansible/pylibssh/blob/8b21ad7/docs/_ext/towncrier_draft_ext.py replacing the conf.py hack. Closes #1639.
Contribution checklist:
(also see CONTRIBUTING.rst for details)
in message body
<issue number>.<type>.rstfor example (588.bugfix.rst)<type>is must be one ofbugfix,feature,deprecation,breaking,doc,misc<your username>"superuser."CONTRIBUTORS(preserving alphabetical order)