Skip to content

Commit f7b4ca3

Browse files
webknjazwebknjaz
committed
Add initial Towncrier integration
Resolves executablebooks#454
1 parent 9362e44 commit f7b4ca3

12 files changed

+317
-1
lines changed

‎.github/chronographer.yml

Lines changed: 11 additions & 0 deletions
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

Lines changed: 18 additions & 0 deletions
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.16.1 - 2021-12-16
422

523
✨ NEW: Add `myst_linkify_fuzzy_links` option.

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

Lines changed: 31 additions & 0 deletions
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

Lines changed: 25 additions & 0 deletions
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

Lines changed: 4 additions & 0 deletions
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

Lines changed: 79 additions & 0 deletions
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

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,31 @@
44
# list see the documentation:
55
# https://www.sphinx-doc.org/en/master/usage/configuration.html
66

7+
from pathlib import Path
8+
79
from sphinx.application import Sphinx
810
from sphinx.util.docutils import SphinxDirective
911

1012
from myst_parser import __version__
1113

14+
15+
# -- Path setup --------------------------------------------------------------
16+
17+
PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve() # pylint: disable=no-member
1218
# -- Project information -----------------------------------------------------
1319

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+
1427
project = "MyST Parser"
1528
copyright = "2020, Executable Book Project"
1629
author = "Executable Book Project"
1730
version = __version__
31+
release = version # FIXME: generate full version w/ setuptools-scm
1832

1933
master_doc = "index"
2034
language = "en"
@@ -27,13 +41,15 @@
2741
extensions = [
2842
"myst_parser",
2943
"sphinx.ext.autodoc",
44+
'sphinx.ext.extlinks',
3045
"sphinx.ext.intersphinx",
3146
"sphinx.ext.viewcode",
3247
"sphinxcontrib.bibtex",
3348
"sphinx_panels",
3449
"sphinxext.rediraffe",
3550
"sphinxcontrib.mermaid",
3651
"sphinxext.opengraph",
52+
'sphinxcontrib.towncrier', # provides `towncrier-draft-entries` directive
3753
]
3854

3955
# Add any paths that contain templates here, relative to this directory.
@@ -42,7 +58,10 @@
4258
# List of patterns, relative to source directory, that match files and
4359
# directories to ignore when looking for source files.
4460
# This pattern also affects html_static_path and html_extra_path.
45-
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
61+
exclude_patterns = [
62+
"_build", "Thumbs.db", ".DS_Store",
63+
'changelog-fragments.d/**', # Towncrier-managed change notes
64+
]
4665

4766

4867
# -- Options for HTML output -------------------------------------------------
@@ -88,6 +107,12 @@
88107
"substitution",
89108
"tasklist",
90109
]
110+
myst_substitutions = {
111+
'project': project,
112+
'release': release,
113+
'release_l': f'`{release}`', # Needed in draft changelog for spelling ext
114+
'version': version,
115+
}
91116
myst_heading_anchors = 2
92117
myst_footnote_transition = True
93118
myst_dmath_double_inline = True
@@ -102,6 +127,14 @@
102127
}
103128

104129

130+
# -- Options for towncrier_draft extension -----------------------------------
131+
132+
towncrier_draft_autoversion_mode = 'draft' # or: 'sphinx-version', 'sphinx-release'
133+
towncrier_draft_include_empty = True
134+
towncrier_draft_working_directory = PROJECT_ROOT_DIR
135+
# Not yet supported: towncrier_draft_config_path = 'pyproject.toml' # relative to cwd
136+
137+
105138
def run_apidoc(app):
106139
"""generate apidoc
107140
@@ -137,6 +170,16 @@ def run_apidoc(app):
137170
os.remove(os.path.join(api_folder, "modules.rst"))
138171

139172

173+
# -- Options for extlinks extension ------------------------------------------
174+
175+
extlinks = {
176+
'issue': (f'{github_repo_url}/issues/%s', '#'), # noqa: WPS323
177+
'pr': (f'{github_repo_url}/pull/%s', 'PR #'), # noqa: WPS323
178+
'commit': (f'{github_repo_url}/commit/%s', ''), # noqa: WPS323
179+
'gh': (f'{github_url}/%s', 'GitHub: '), # noqa: WPS323
180+
'user': (f'{github_sponsors_url}/%s', '@'), # noqa: WPS323
181+
}
182+
140183
intersphinx_mapping = {
141184
"python": ("https://docs.python.org/3.7", None),
142185
"sphinx": ("https://www.sphinx-doc.org/en/master", None),

‎docs/develop/_changelog.md

Lines changed: 19 additions & 0 deletions
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

Lines changed: 3 additions & 0 deletions
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

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,50 @@ known_first_party = ["myst_parser", "tests"]
88
known_third_party = ["docutils", "markdown_it", "sphinx"]
99
# Group first party and local folder imports together
1010
no_lines_before = "LOCALFOLDER"
11+
12+
[tool.towncrier]
13+
directory = "docs/changelog-fragments.d/"
14+
filename = "CHANGELOG.md"
15+
issue_format = "{{issue}}`{issue}`"
16+
start_string = "<!-- towncrier release notes start -->\n\n"
17+
template = "docs/changelog-fragments.d/.CHANGELOG-TEMPLATE.md.j2"
18+
title_format = "## {version} - ({project_date})"
19+
underlines = ["##", "###", "####", "#####"]
20+
21+
[[tool.towncrier.section]]
22+
path = ""
23+
24+
[[tool.towncrier.type]]
25+
directory = "bugfix"
26+
name = "Bugfixes"
27+
showcontent = true
28+
29+
[[tool.towncrier.type]]
30+
directory = "feature"
31+
name = "Features"
32+
showcontent = true
33+
34+
[[tool.towncrier.type]]
35+
directory = "deprecation"
36+
name = "Deprecations (removal in next major release)"
37+
showcontent = true
38+
39+
[[tool.towncrier.type]]
40+
directory = "breaking"
41+
name = "Backward incompatible changes"
42+
showcontent = true
43+
44+
[[tool.towncrier.type]]
45+
directory = "doc"
46+
name = "Documentation"
47+
showcontent = true
48+
49+
[[tool.towncrier.type]]
50+
directory = "misc"
51+
name = "Miscellaneous"
52+
showcontent = true
53+
54+
[[tool.towncrier.type]]
55+
directory = "internal"
56+
name = "Contributor-facing changes"
57+
showcontent = true

‎setup.cfg

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ rtd =
7171
sphinxext-rediraffe~=0.2
7272
sphinxcontrib.mermaid~=0.6.3
7373
sphinxext-opengraph~=0.4.2
74+
sphinxcontrib-towncrier ~= 0.2.0a0
7475
testing =
7576
beautifulsoup4
7677
coverage

0 commit comments

Comments
 (0)