Skip to content

Commit cefdc1d

Browse files
felixfonteinfelixfontein
authored
Improve documentation (#144)
* Convert documentation to MarkDown. * Add mkdocs site. * Add RTD config.
1 parent db00056 commit cefdc1d

13 files changed

+1056
-615
lines changed

‎.readthedocs.yml

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
# Copyright (c) Ansible Project
3+
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
4+
# SPDX-License-Identifier: GPL-3.0-or-later
5+
6+
version: 2
7+
build:
8+
os: ubuntu-22.04
9+
tools:
10+
python: "3.11"
11+
commands:
12+
- pip install -U nox
13+
- mkdir -p _readthedocs/html/
14+
- nox -e mkdocs -- build --site-dir=_readthedocs/html

‎README.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,10 @@ SPDX-License-Identifier: GPL-3.0-or-later
1212
A changelog generator used by ansible-core and Ansible collections.
1313

1414
- Using the
15-
[`antsibull-changelog` CLI tool for collections](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/changelogs.rst).
15+
[`antsibull-changelog` CLI tool for collections](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/changelogs.md).
1616
- Using the
17-
[`antsibull-changelog` CLI tool for other projects](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/other-projects.rst).
18-
- Documentation on the [`changelogs/config.yaml` configuration file for `antsibull-changelog`](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/changelog-configuration.rst).
17+
[`antsibull-changelog` CLI tool for other projects](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/other-projects.md).
18+
- Documentation on the [`changelogs/config.yaml` configuration file for `antsibull-changelog`](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/changelog-configuration.md).
1919
- Documentation on the
2020
[`changelog.yaml` format](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/changelog.yaml-format.md).
2121

@@ -38,7 +38,7 @@ The `toml` extra is always available, but it is noop on Python >= 3.11,
3838
as `tomllib` is part of the standard library.
3939

4040
For more information, see the
41-
[documentation](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/changelogs.rst).
41+
[documentation](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/changelogs.md).
4242

4343
## Development
4444

‎docs-requirements.txt

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Copyright (c) Ansible Project
2+
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
3+
# SPDX-License-Identifier: GPL-3.0-or-later
4+
5+
mkdocs
6+
mkdocs-ansible

‎docs/changelog-configuration.md

+289
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
<!--
2+
Copyright (c) Ansible Project
3+
GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
4+
SPDX-License-Identifier: GPL-3.0-or-later
5+
-->
6+
7+
# Configuration Settings for antsibull-changelog
8+
9+
This document describes all settings that are supported in
10+
`changelogs/config.yaml`.
11+
12+
## General options
13+
14+
### `always_refresh` (string)
15+
16+
Allowed values are `none`, `full`, or a comma-separated combination of
17+
one or more of `plugins`, `plugins-without-removal`, `fragments` and
18+
`fragments-without-archives`.
19+
20+
If `true` is passed, it will be converted to `full`. If `false` is
21+
passed, it will be converted to `none`.
22+
23+
For details, see ["Updating/Refreshing changelog.yaml" in the main
24+
documentation](changelogs.md#updatingrefreshing-changelogyaml).
25+
26+
### `archive_path_template` (optional string)
27+
28+
The default value is `null`.
29+
30+
When `keep_fragments` is set to `false`, and this setting is defined,
31+
fragments will be copied to the path specified by this setting after a
32+
release is made. This setting is assumed to point to a directory, and
33+
the placeholder `{version}` can be used to make the destination
34+
dependent on the version number of the new release. If the directory
35+
does not yet exist, it will be created.
36+
37+
### `changelog_filename_template` (string)
38+
39+
The default value is `CHANGELOG-v%s.rst` for existing configurations,
40+
and `../CHANGELOG.rst` for new configurations.
41+
42+
This is the path relative to the `changelogs/` directory where the
43+
reStructuredText version of the changelog is written to. The placeholder
44+
`%s` will be replaced by the first `changelog_filename_version_depth`
45+
parts of the version of the release.
46+
47+
> [!NOTE]
48+
> The file extension (default `.rst`) will always be replaced by the
49+
> extension matching the output format (see [`output_format`](#output_format-list-of-strings)).
50+
> Therefore the extension provided here will always be ignored.
51+
52+
### `changelog_filename_version_depth` (integer)
53+
54+
The default value is 2 for existing configurations, and 0 for new
55+
configurations.
56+
57+
Determines the number of parts of the current release version to be used
58+
when replacing `%s` in `changelog_filename_template` (see above). For
59+
the value 2, version 1.2.3 will result in the string `1.2`. The value 0
60+
results in the empty string.
61+
62+
### `changes_file` (string)
63+
64+
The default value is `.changes.yaml` for existing configurations, and
65+
`changelog.yaml` for new configurations.
66+
67+
The YAML file where the changelog is stored in a machine-readable form.
68+
This is relative to the `changelogs/` directory and should not be
69+
changed, since `changelogs/changelog.yaml` is the standard place for the
70+
machine-readable file which is expected to be there by the Ansible
71+
Community Distribution changelog generator.
72+
73+
### `changes_format` (string)
74+
75+
The default value is `classic` for existing configurations, and
76+
`combined` for new configurations.
77+
78+
Determines whether `changes_file` contains only references to changelog
79+
fragments or plugins (was used internally by Ansible until version 2.9),
80+
or whether all fragments and plugin data is stored inside the file (used
81+
by Ansible 2.10 and in collections). Should never be set to `classic`,
82+
except when using the changelog generator for Ansible 2.9 or earlier.
83+
84+
Note that support for `classic` is **DEPRECATED** and will be removed in
85+
a future release. The field will from then on be required.
86+
87+
### `flatmap` (optional boolean)
88+
89+
The default value is `null`.
90+
91+
Can be set to `true` or `false` explicitly to enable respectively
92+
disable flatmapping. Since flatmapping is disabled by default (except
93+
for ansible-core), this is effectively only needed for the big community
94+
collections `community.general` and `community.network`.
95+
96+
When enabled, a plugin `foo.bar.subdir.dir.plugin_name` will be
97+
mentioned as `plugin_name` or `foo.bar.plugin_name` (if `use_fqcn` is
98+
`true`), instead of as `subdir.dir.plugin_name` respectively
99+
`foo.bar.subdir.dir.plugin_name`.
100+
101+
### `is_other_project` (boolean)
102+
103+
The default value is `false`.
104+
105+
If set to `true`, does not look for `galaxy.yml` and does not look for
106+
new Ansible objects (plugins, modules and roles). This allows the
107+
changelog generator to be used for projects which are not
108+
ansible-core/-base or an Ansible collection.
109+
110+
### `ignore_other_fragment_extensions` (boolean)
111+
112+
The default value is `false` for existing configurations, and `true` for
113+
new configurations.
114+
115+
If set to `true`, only `.yml` and `.yaml` fragment filenames are
116+
considered which do not start with a dot. This is compatible with what
117+
`ansible-test sanity --test changelog` enforces. If set to `false`
118+
(default if not specified), all filenames that do not start with a dot
119+
are considered.
120+
121+
### `keep_fragments` (boolean)
122+
123+
The default value is `false` (except if `changes_format` is `classic`).
124+
125+
If set to `false`, the fragment files will be removed after a release is
126+
done. If set to `true`, fragment files for old releases are kept.
127+
128+
If fragment files should be moved to another directory after release,
129+
set this setting to `false` and set `archive_path_template`.
130+
131+
See also `prevent_known_fragments`.
132+
133+
### `mention_ancestor` (boolean)
134+
135+
The default value is `true`.
136+
137+
If an ancestor is defined in `changelogs/changelog.yaml`, determines
138+
whether it should be mentioned at the beginning of the changelog or not.
139+
If set to `true`,
140+
`This changelog describes changes after version {ancestor}` will be
141+
inserted at the top of the changelog.
142+
143+
### `notes_dir` (string)
144+
145+
The default value is `fragments`.
146+
147+
The name of the subdirectory of `changelogs/` that contains the
148+
changelog fragments.
149+
150+
### `prelude_name` (string)
151+
152+
The default value is `release_summary`.
153+
154+
Name of the prelude section to be used in changelog fragments. This
155+
section is special, in that it does not accept a list, but a string.
156+
157+
### `prelude_title` (string)
158+
159+
The default value is `Release Summary`.
160+
161+
The title for the section whose name is set in `prelude_name`.
162+
163+
### `prevent_known_fragments` (optional boolean)
164+
165+
The default value is the same value as the `keep_fragments` option.
166+
167+
If set to `true`, will not add changelog fragments to a release whose
168+
filename was already used in the past. This was the default behavior
169+
before antsibull-changelog 0.9.0. From 0.9.0 on, it is set to `false` by
170+
default if `keep_fragments` is `false`.
171+
172+
If `keep_fragments` is set to `false` later-on when some fragments from
173+
older releases are still there, and you want to keep them, make sure to
174+
set `prevent_known_fragments` explicitly to `true`. Otherwise they will
175+
be added again to the next release.
176+
177+
### `sanitize_changelog` (boolean)
178+
179+
The default value is `false` for existing configurations, and `true` for
180+
new configurations.
181+
182+
Remove all invalid and superfluous information when loading a
183+
`changelogs/changelog.yaml` file.
184+
185+
### `sections` (list of two-element lists of strings)
186+
187+
The default value is:
188+
189+
- - major_changes
190+
- Major Changes
191+
- - minor_changes
192+
- Minor Changes
193+
- - breaking_changes
194+
- Breaking Changes / Porting Guide
195+
- - deprecated_features
196+
- Deprecated Features
197+
- - removed_features
198+
- Removed Features (previously deprecated)
199+
- - security_fixes
200+
- Security Fixes
201+
- - bugfixes
202+
- Bugfixes
203+
- - known_issues
204+
- Known Issues
205+
206+
Lists all section names (first element) and their titles (second
207+
element). The only two sections not listed here are the prelude section
208+
(`release_summary` / "Release Summary") and the trivial section
209+
(`trivial`, no title).
210+
211+
It is not recommended to change this list, except possibly adjust
212+
section titles. Collections using other section names will cause
213+
problems with the Ansible Community Distribution changelog generation.
214+
215+
### `title` (string)
216+
217+
The default value is the titlecase of the collection's namespace and
218+
name.
219+
220+
The title is shown at the top of the changelog.
221+
222+
### `trivial_section_name` (optional string)
223+
224+
The default value is `trivial` for collections and other projects, and
225+
`null` for ansible-core/ansible-base.
226+
227+
This defines a section that is not included in the generated
228+
reStructuredText version of the changelog. It can be used to add
229+
changelog fragments to changes that are so minor (trivial) that they
230+
should not appear in the changelog, or that are irrelevant to the user
231+
(for example changes in the CI system used). When set to `null`, no
232+
trivial section is allowed.
233+
234+
### `use_fqcn` (boolean)
235+
236+
The default value is `false` for existing configurations, and `true` for
237+
new configurations.
238+
239+
When set to `true`, uses FQCN (Fully Qualified Collection Names) when
240+
mentioning new plugins and modules. This means that `namespace.name.`
241+
is prepended to the plugin respectively module names.
242+
243+
### `output_format` (list of strings)
244+
245+
The default is `["rst"]`.
246+
247+
A list of output formats to write the changelog as. Supported formats
248+
are `rst` for ReStructuredText and `md` for MarkDown.
249+
250+
## Deprecated options
251+
252+
### `new_plugins_after_name` (string)
253+
254+
The default value is `''` (empty string).
255+
256+
This setting is not used.
257+
258+
## Ansible-core/-base specific options
259+
260+
These options are only used for the changelog for ansible-core, i.e. in
261+
the ansible/ansible GitHub repository.
262+
263+
### `use_semantic_versioning` (boolean)
264+
265+
The default value is `false`.
266+
267+
If set to `true`, assumes that ansible-core use semantic versioning
268+
instead of the classic Ansible version numbers. This is mainly relevant
269+
for pre-releases. If set to `true`, `release_tag_re` and
270+
`pre_release_tag_re` are ignored.
271+
272+
### `release_tag_re` (string)
273+
274+
The default value is `((?:[\d.ab]|rc)+)`.
275+
276+
This value is used to detect versions that are proper release versions,
277+
and not prereleases. This is a regular expression matching the version
278+
string preprended with `v`.
279+
280+
This setting is ignored if `use_semantic_versioning` is set to `true`.
281+
282+
### `pre_release_tag_re` (string)
283+
284+
The default value is `(?P<pre_release>\.\d+(?:[ab]|rc)+\d*)$`.
285+
286+
This value is used to detect versions that are prereleases. This is a
287+
regular expression matching the version string preprended with `v`.
288+
289+
This setting is ignored if `use_semantic_versioning` is set to `true`.

0 commit comments

Comments
 (0)