Skip to content

Commit c866013

Browse files
webknjazwebknjaz
committed
Add initial Towncrier integration
Resolves executablebooks#454
1 parent 28725fc commit c866013

11 files changed

+333
-3
lines changed

‎.github/chronographer.yml

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
enforce_name:
3+
suffix: .md
4+
exclude:
5+
bots:
6+
- dependabot-preview
7+
- dependabot
8+
- patchback
9+
humans:
10+
- pyup-bot
11+
...

‎CHANGELOG.md

+18
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,23 @@
11
# Changelog
22

3+
[//]: # (DO-NOT-REMOVE-versioning-promise-START)
4+
5+
```{note}
6+
The change notes follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
7+
except for the title formatting, and this project adheres to [Semantic
8+
Versioning](https://semver.org/spec/v2.0.0.html).
9+
```
10+
11+
<!--
12+
Do *NOT* manually add changelog entries here!
13+
This changelog is managed by Towncrier and is built at release time.
14+
See https://myst-parser.rtfd.io/en/latest/develop/contributing#adding-change-notes-with-your-prs
15+
for details. Or read
16+
https://github.com/executablebooks/MyST-Parser/tree/master/docs/changelog-fragments.d#adding-change-notes-with-your-prs
17+
-->
18+
19+
<!-- towncrier release notes start -->
20+
321
## 0.18.1 - 2022-27-09
422

523
Full Changelog: [v0.18.0...v0.18.1](https://github.com/executablebooks/MyST-Parser/compare/v0.18.0...v0.18.1)

‎docs/changelog-fragments.d/.CHANGELOG-TEMPLATE.md.j2

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
2+
{% for section, _ in sections.items() %}
3+
{% set title_prefix = underlines[0] %}
4+
{% if section %}
5+
{{ title_prefix }} {{ section }}
6+
{% set title_prefix = underlines[1] %}
7+
{% endif %}
8+
9+
{% if sections[section] %}
10+
{% for category, val in definitions.items() if category in sections[section] %}
11+
{{ title_prefix }} {{ definitions[category]['name'] }}
12+
{% if definitions[category]['showcontent'] %}
13+
14+
{% for text, values in sections[section][category].items() %}
15+
* {{ text }}
16+
({{ values|join(',\n ') }})
17+
{% endfor -%}
18+
19+
{% else %}
20+
* {{ sections[section][category]['']|join(', ') }}
21+
{% endif %}
22+
23+
{% if sections[section][category]|length == 0 %}
24+
No significant changes.
25+
{% endif %}
26+
{% endfor %}
27+
28+
{% else %}
29+
No significant changes.
30+
{% endif %}
31+
{% endfor %}

‎docs/changelog-fragments.d/.gitignore

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
*
2+
!.CHANGELOG-TEMPLATE.md.j2
3+
!.gitignore
4+
!README.md
5+
!*.bugfix
6+
!*.bugfix.md
7+
!*.bugfix.*.md
8+
!*.breaking
9+
!*.breaking.md
10+
!*.breaking.*.md
11+
!*.deprecation
12+
!*.deprecation.md
13+
!*.deprecation.*.md
14+
!*.doc
15+
!*.doc.md
16+
!*.doc.*.md
17+
!*.feature
18+
!*.feature.md
19+
!*.feature.*.md
20+
!*.internal
21+
!*.internal.md
22+
!*.internal.*.md
23+
!*.misc
24+
!*.misc.md
25+
!*.misc.*.md

‎docs/changelog-fragments.d/454.misc.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Added changelog fragment management infrastructure using [Towncrier]
2+
-- by {user}`webknjaz`
3+
4+
[Towncrier]: https://github.com/twisted/towncrier

‎docs/changelog-fragments.d/README.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
<!-- markdownlint-disable first-line-heading -->
2+
3+
(_myst_parser_adding_changelog_fragments)=
4+
5+
## Adding change notes with your PRs
6+
7+
It is very important to maintain a log for news of how
8+
updating to the new version of the software will affect
9+
end-users. This is why we enforce collection of the change
10+
fragment files in pull requests as per [Towncrier philosophy].
11+
12+
The idea is that when somebody makes a change, they must record
13+
the bits that would affect end-users only including information
14+
that would be useful to them. Then, when the maintainers publish
15+
a new release, they'll automatically use these records to compose
16+
a change log for the respective version. It is important to
17+
understand that including unnecessary low-level implementation
18+
related details generates noise that is not particularly useful
19+
to the end-users most of the time. And so such details should be
20+
recorded in the Git history rather than a changelog.
21+
22+
## Alright! So how do I add a news fragment?
23+
24+
To submit a change note about your PR, add a text file into the
25+
`docs/changelog-fragments.d/` folder. It should contain an
26+
explanation of what applying this PR will change in the way
27+
end-users interact with the project. One sentence is usually
28+
enough but feel free to add as many details as you feel necessary
29+
for the users to understand what it means.
30+
31+
**Use the past tense** for the text in your fragment because,
32+
combined with others, it will be a part of the "news digest"
33+
telling the readers **what changed** in a specific version of
34+
the library *since the previous version*. You should also use
35+
[MyST Markdown] syntax for highlighting code (inline or block),
36+
linking parts of the docs or external sites.
37+
At the end, sign your change note by adding ```-- by
38+
{user}`github-username``` (replace `github-username` with
39+
your own!).
40+
41+
Finally, name your file following the convention that Towncrier
42+
understands: it should start with the number of an issue or a
43+
PR followed by a dot, then add a patch type, like `feature`,
44+
`bugfix`, `doc`, `misc` etc., and add `.md` as a suffix. If you
45+
need to add more than one fragment, you may add an optional
46+
sequence number (delimited with another period) between the type
47+
and the suffix.
48+
49+
## Examples for changelog entries adding to your Pull Requests
50+
51+
File `docs/changelog-fragments.d/666.doc.md`:
52+
53+
```md
54+
Added a `{user}` role to Sphinx config -- by {user}`webknjaz`
55+
```
56+
57+
File `docs/changelog-fragments.d/116.feature.md`:
58+
59+
```md
60+
Added support for nested module options (suboptions)
61+
-- by {user}`tomaciazek`
62+
```
63+
64+
File `docs/changelog-fragments.d/140.bugfix.md`:
65+
66+
```md
67+
Implemented opening standalone Ansible files that have no workspace
68+
associated -- by {user}`ganeshrn`
69+
```
70+
71+
```{tip}
72+
See `pyproject.toml` for all available categories
73+
(`tool.towncrier.type`).
74+
```
75+
76+
[MyST Markdown]:
77+
https://myst-parser.rtfd.io/en/latest/syntax/syntax.html
78+
[Towncrier philosophy]:
79+
https://towncrier.rtfd.io/en/actual-freaking-docs/#philosophy

‎docs/conf.py

+54-3
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,39 @@
55
# https://www.sphinx-doc.org/en/master/usage/configuration.html
66

77
from datetime import date
8+
from functools import partial
9+
from pathlib import Path
810

11+
from setuptools_scm import get_version
912
from sphinx.application import Sphinx
1013

11-
from myst_parser import __version__
14+
# -- Path setup --------------------------------------------------------------
1215

16+
PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve() # pylint: disable=no-member
17+
get_scm_version = partial(get_version, root=PROJECT_ROOT_DIR)
1318
# -- Project information -----------------------------------------------------
1419

20+
github_url = "https://github.com"
21+
github_repo_org = "ansible"
22+
github_repo_name = "ansible-language-server"
23+
github_repo_slug = f"{github_repo_org}/{github_repo_name}"
24+
github_repo_url = f"{github_url}/{github_repo_slug}"
25+
github_sponsors_url = f"{github_url}/sponsors"
26+
1527
project = "MyST Parser"
1628
copyright = f"{date.today().year}, Executable Book Project"
1729
author = "Executable Book Project"
18-
version = __version__
30+
31+
# The short X.Y version
32+
version = ".".join(
33+
get_scm_version(local_scheme="no-local-version",).split(
34+
"."
35+
)[:3],
36+
)
37+
38+
# The full version, including alpha/beta/rc tags
39+
release = get_scm_version()
40+
1941

2042
master_doc = "index"
2143
language = "en"
@@ -28,12 +50,14 @@
2850
extensions = [
2951
"myst_parser",
3052
"sphinx.ext.autodoc",
53+
"sphinx.ext.extlinks",
3154
"sphinx.ext.intersphinx",
3255
"sphinx.ext.viewcode",
3356
"sphinx_design",
3457
"sphinxext.rediraffe",
3558
"sphinxcontrib.mermaid",
3659
"sphinxext.opengraph",
60+
"sphinxcontrib.towncrier", # provides `towncrier-draft-entries` directive
3761
]
3862

3963
# Add any paths that contain templates here, relative to this directory.
@@ -42,7 +66,12 @@
4266
# List of patterns, relative to source directory, that match files and
4367
# directories to ignore when looking for source files.
4468
# This pattern also affects html_static_path and html_extra_path.
45-
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
69+
exclude_patterns = [
70+
"_build",
71+
"Thumbs.db",
72+
".DS_Store",
73+
"changelog-fragments.d/**", # Towncrier-managed change notes
74+
]
4675

4776

4877
# -- Options for HTML output -------------------------------------------------
@@ -93,6 +122,12 @@
93122
"attrs_image",
94123
]
95124
myst_number_code_blocks = ["typescript"]
125+
myst_substitutions = {
126+
"project": project,
127+
"release": release,
128+
"release_l": f"`{release}`", # Needed in draft changelog for spelling ext
129+
"version": version,
130+
}
96131
myst_heading_anchors = 2
97132
myst_footnote_transition = True
98133
myst_dmath_double_inline = True
@@ -114,6 +149,22 @@
114149

115150
suppress_warnings = ["myst.strikethrough"]
116151

152+
# -- Options for towncrier_draft extension -----------------------------------
153+
154+
towncrier_draft_autoversion_mode = "draft" # or: 'sphinx-version', 'sphinx-release'
155+
towncrier_draft_include_empty = True
156+
towncrier_draft_working_directory = PROJECT_ROOT_DIR
157+
# towncrier_draft_config_path = 'pyproject.toml' # relative to cwd
158+
159+
# -- Options for extlinks extension ------------------------------------------
160+
161+
extlinks = {
162+
"issue": (f"{github_repo_url}/issues/%s", "#%s"), # noqa: WPS323
163+
"pr": (f"{github_repo_url}/pull/%s", "PR #%s"), # noqa: WPS323
164+
"commit": (f"{github_repo_url}/commit/%s", "%s"), # noqa: WPS323
165+
"gh": (f"{github_url}/%s", "GitHub: %s"), # noqa: WPS323
166+
"user": (f"{github_sponsors_url}/%s", "@%s"), # noqa: WPS323
167+
}
117168

118169
intersphinx_mapping = {
119170
"python": ("https://docs.python.org/3.7", None),

‎docs/develop/_changelog.md

+19
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,23 @@
1+
# Changelog
2+
3+
```{include} ../../CHANGELOG.md
4+
:end-before: <!-- towncrier release notes start -->
5+
:start-after: (DO-NOT-REMOVE-versioning-promise-START)
6+
7+
```
8+
9+
<!-- markdownlint-disable-next-line no-space-in-emphasis -->
10+
## {{ release_l }}, as of {sub-ref}`today` _{subscript}`/UNRELEASED DRAFT/`_
11+
12+
```{important} This version is not yet released and is under active development
13+
```
14+
15+
```{towncrier-draft-entries}
16+
```
17+
118
```{include} ../../CHANGELOG.md
219
:relative-docs: docs/
320
:relative-images:
21+
:start-after: <!-- towncrier release notes start -->
22+
423
```

‎docs/develop/contributing.md

+3
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,9 @@ For documentation build tests:
7171
>> make html-strict
7272
```
7373

74+
```{include} ../changelog-fragments.d/README.md
75+
```
76+
7477
```{seealso}
7578
{ref}`develop/testing`
7679
```

‎pyproject.toml

+49
Original file line numberDiff line numberDiff line change
@@ -54,11 +54,13 @@ linkify = ["linkify-it-py~=1.0"]
5454
# Note: This is only required for internal use
5555
rtd = [
5656
"ipython",
57+
"setuptools-scm ~= 7.0.5",
5758
"sphinx-book-theme",
5859
"sphinx-design",
5960
"sphinxext-rediraffe~=0.2.7",
6061
"sphinxcontrib.mermaid~=0.7.1",
6162
"sphinxext-opengraph~=0.6.3",
63+
"sphinxcontrib-towncrier ~= 0.3.0a0",
6264
]
6365
testing = [
6466
"beautifulsoup4",
@@ -108,3 +110,50 @@ ignore_missing_imports = true
108110

109111
[tool.coverage.run]
110112
omit = ["*/_docs.py"]
113+
114+
[tool.towncrier]
115+
directory = "docs/changelog-fragments.d/"
116+
filename = "CHANGELOG.md"
117+
issue_format = "{{issue}}`{issue}`"
118+
start_string = "<!-- towncrier release notes start -->\n\n"
119+
template = "docs/changelog-fragments.d/.CHANGELOG-TEMPLATE.md.j2"
120+
title_format = "## {version} - ({project_date})"
121+
underlines = ["##", "###", "####", "#####"]
122+
123+
[[tool.towncrier.section]]
124+
path = ""
125+
126+
[[tool.towncrier.type]]
127+
directory = "bugfix"
128+
name = "Bugfixes"
129+
showcontent = true
130+
131+
[[tool.towncrier.type]]
132+
directory = "feature"
133+
name = "Features"
134+
showcontent = true
135+
136+
[[tool.towncrier.type]]
137+
directory = "deprecation"
138+
name = "Deprecations (removal in next major release)"
139+
showcontent = true
140+
141+
[[tool.towncrier.type]]
142+
directory = "breaking"
143+
name = "Backward incompatible changes"
144+
showcontent = true
145+
146+
[[tool.towncrier.type]]
147+
directory = "doc"
148+
name = "Documentation"
149+
showcontent = true
150+
151+
[[tool.towncrier.type]]
152+
directory = "misc"
153+
name = "Miscellaneous"
154+
showcontent = true
155+
156+
[[tool.towncrier.type]]
157+
directory = "internal"
158+
name = "Contributor-facing changes"
159+
showcontent = true

0 commit comments

Comments
 (0)