Skip to content

Commit c0a76ec

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

12 files changed

+336
-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.16.1 - 2021-12-16
422

523
✨ NEW: Add `myst_linkify_fuzzy_links` option.

‎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

+57-3
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,42 @@
44
# list see the documentation:
55
# https://www.sphinx-doc.org/en/master/usage/configuration.html
66

7+
from functools import partial
8+
from pathlib import Path
9+
10+
from setuptools_scm import get_version
11+
712
from sphinx.application import Sphinx
813
from sphinx.util.docutils import SphinxDirective
914

10-
from myst_parser import __version__
1115

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

22+
github_url = 'https://github.com'
23+
github_repo_org = 'ansible'
24+
github_repo_name = 'ansible-language-server'
25+
github_repo_slug = f'{github_repo_org}/{github_repo_name}'
26+
github_repo_url = f'{github_url}/{github_repo_slug}'
27+
github_sponsors_url = f'{github_url}/sponsors'
28+
1429
project = "MyST Parser"
1530
copyright = "2020, Executable Book Project"
1631
author = "Executable Book Project"
17-
version = __version__
32+
33+
# The short X.Y version
34+
version = '.'.join(
35+
get_scm_version(
36+
local_scheme='no-local-version',
37+
).split('.')[:3],
38+
)
39+
40+
# The full version, including alpha/beta/rc tags
41+
release = get_scm_version()
42+
1843

1944
master_doc = "index"
2045
language = "en"
@@ -27,13 +52,15 @@
2752
extensions = [
2853
"myst_parser",
2954
"sphinx.ext.autodoc",
55+
'sphinx.ext.extlinks',
3056
"sphinx.ext.intersphinx",
3157
"sphinx.ext.viewcode",
3258
"sphinxcontrib.bibtex",
3359
"sphinx_panels",
3460
"sphinxext.rediraffe",
3561
"sphinxcontrib.mermaid",
3662
"sphinxext.opengraph",
63+
'sphinxcontrib.towncrier', # provides `towncrier-draft-entries` directive
3764
]
3865

3966
# Add any paths that contain templates here, relative to this directory.
@@ -42,7 +69,10 @@
4269
# List of patterns, relative to source directory, that match files and
4370
# directories to ignore when looking for source files.
4471
# This pattern also affects html_static_path and html_extra_path.
45-
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
72+
exclude_patterns = [
73+
"_build", "Thumbs.db", ".DS_Store",
74+
'changelog-fragments.d/**', # Towncrier-managed change notes
75+
]
4676

4777

4878
# -- Options for HTML output -------------------------------------------------
@@ -88,6 +118,12 @@
88118
"substitution",
89119
"tasklist",
90120
]
121+
myst_substitutions = {
122+
'project': project,
123+
'release': release,
124+
'release_l': f'`{release}`', # Needed in draft changelog for spelling ext
125+
'version': version,
126+
}
91127
myst_heading_anchors = 2
92128
myst_footnote_transition = True
93129
myst_dmath_double_inline = True
@@ -102,6 +138,14 @@
102138
}
103139

104140

141+
# -- Options for towncrier_draft extension -----------------------------------
142+
143+
towncrier_draft_autoversion_mode = 'draft' # or: 'sphinx-version', 'sphinx-release'
144+
towncrier_draft_include_empty = True
145+
towncrier_draft_working_directory = PROJECT_ROOT_DIR
146+
# Not yet supported: towncrier_draft_config_path = 'pyproject.toml' # relative to cwd
147+
148+
105149
def run_apidoc(app):
106150
"""generate apidoc
107151
@@ -137,6 +181,16 @@ def run_apidoc(app):
137181
os.remove(os.path.join(api_folder, "modules.rst"))
138182

139183

184+
# -- Options for extlinks extension ------------------------------------------
185+
186+
extlinks = {
187+
'issue': (f'{github_repo_url}/issues/%s', '#'), # noqa: WPS323
188+
'pr': (f'{github_repo_url}/pull/%s', 'PR #'), # noqa: WPS323
189+
'commit': (f'{github_repo_url}/commit/%s', ''), # noqa: WPS323
190+
'gh': (f'{github_url}/%s', 'GitHub: '), # noqa: WPS323
191+
'user': (f'{github_sponsors_url}/%s', '@'), # noqa: WPS323
192+
}
193+
140194
intersphinx_mapping = {
141195
"python": ("https://docs.python.org/3.7", None),
142196
"sphinx": ("https://www.sphinx-doc.org/en/master", 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

+47
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

+2
Original file line numberDiff line numberDiff line change
@@ -65,12 +65,14 @@ linkify =
6565
# Note: This is only required for internal use
6666
rtd =
6767
ipython
68+
setuptools-scm ~= 6.3.2
6869
sphinx-book-theme~=0.1.0
6970
sphinx-panels~=0.5.2
7071
sphinxcontrib-bibtex~=2.1
7172
sphinxext-rediraffe~=0.2
7273
sphinxcontrib.mermaid~=0.6.3
7374
sphinxext-opengraph~=0.4.2
75+
sphinxcontrib-towncrier ~= 0.2.0a0
7476
testing =
7577
beautifulsoup4
7678
coverage

0 commit comments

Comments
 (0)