Improve README, add MarkDown changelog, and mention documentation in …

…the PyPI links (#249)

* Improve README and mention documentation in the PyPI links.

* Add MarkDown changelog.

* Improve wording.

Co-authored-by: Maxwell G <maxwell@gtmx.me>

---------

Co-authored-by: Maxwell G <maxwell@gtmx.me>

CHANGELOG.md.license

@@ -0,0 +1,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)
+SPDX-FileCopyrightText: Ansible Project
+SPDX-License-Identifier: GPL-3.0-or-later

CHANGELOG.rst

@@ -4,7 +4,6 @@ antsibull-docs -- Ansible Documentation Build Scripts Release Notes
 
 .. contents:: Topics
 
-
 v2.7.0
 ======
 
@@ -83,7 +82,6 @@ There will be a follow-up release after `Ansible Galaxy <https://galaxy.ansible.
 switched to the new ``galaxy_ng`` codebase, which is scheduled for September 30th.
 That release will only adjust the URLs to Galaxy, except potentially bugfixes.
 
-
 Minor Changes
 -------------
 

README.md

@@ -11,15 +11,9 @@ SPDX-License-Identifier: GPL-3.0-or-later
 [![Build CSS testing badge](https://github.com/ansible-community/antsibull-docs/workflows/Build%20CSS/badge.svg?event=push&branch=main)](https://github.com/ansible-community/antsibull-docs/actions?query=workflow%3A%22Build+CSS%22+branch%3Amain)
 [![Codecov badge](https://img.shields.io/codecov/c/github/ansible-community/antsibull-docs)](https://codecov.io/gh/ansible-community/antsibull-docs)
 
-Tooling for building Ansible documentation.
+Tooling for building Ansible documentation. This is mainly the `antsibull-docs` command and the [Sphinx extension](https://www.sphinx-doc.org/en/master/), ``sphinx_antsibull_ext``. Please check out the [documentation](https://ansible.readthedocs.io/projects/antsibull-docs/) for more information.
 
-Script that is here:
-
-* antsibull-docs - Extracts documentation from ansible plugins
-
-This also includes a [Sphinx extension](https://www.sphinx-doc.org/en/master/) `sphinx_antsibull_ext` which provides a minimal CSS file to render the output of `antsibull-docs` correctly.
-
-You can find a list of changes in [the antsibull-docs changelog](./CHANGELOG.md).
+You can find a list of changes in [the antsibull-docs changelog](https://github.com/ansible-community/antsibull-docs/blob/main/CHANGELOG.md).
 
 antsibull-docs is covered by the [Ansible Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html).
 
@@ -33,36 +27,6 @@ We explicitly exclude code compatibility. **antsibull-docs is not supposed to be
 
 If you are interested in library support for interpreting Ansible markup, please take a look at [the antsibull-docs-parser project](https://github.com/ansible-community/antsibull-docs-parser).
 
-## Using the Sphinx extension
-
-Include it in your Sphinx configuration ``conf.py``:
-
-```python
-# Add it to 'extensions':
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'notfound.extension', 'sphinx_antsibull_ext']
-```
-
-## Updating the CSS file for the Sphinx extension
-
-The CSS file [sphinx_antsibull_ext/antsibull-minimal.css](https://github.com/ansible-community/antsibull-docs/blob/main/sphinx_antsibull_ext/antsibull-minimal.css) is built from [sphinx_antsibull_ext/css/antsibull-minimal.scss](https://github.com/ansible-community/antsibull-docs/blob/main/sphinx_antsibull_ext/src/antsibull-minimal.scss) using [SASS](https://sass-lang.com/) and [postcss](https://postcss.org/) using [autoprefixer](https://github.com/postcss/autoprefixer) and [cssnano](https://cssnano.co/).
-
-Use the script `build.sh` in `sphinx_antsibull_ext/css/` to build the `.css` file from the `.scss` file:
-
-```console
-cd sphinx_antsibull_ext/css/
-./build-css.sh
-```
-
-For this to work, you need to make sure that `sassc` and `postcss` are on your path and that the autoprefixer and nanocss modules are installed:
-
-```console
-# Debian:
-apt-get install sassc
-
-# PostCSS, autoprefixer and cssnano require nodejs/npm:
-npm install -g autoprefixer cssnano postcss postcss-cli
-```
-
 ## Development
 
 Install and run `nox` to run all tests. That's it for simple contributions!
@@ -109,6 +73,27 @@ pip install -e '.[dev]' -e ../antsibull-core -e ../antsibull-docs-parser
 nox
 ```
 
+## Updating the CSS file for the Sphinx extension
+
+The CSS file [sphinx_antsibull_ext/antsibull-minimal.css](https://github.com/ansible-community/antsibull-docs/blob/main/sphinx_antsibull_ext/antsibull-minimal.css) is built from [sphinx_antsibull_ext/css/antsibull-minimal.scss](https://github.com/ansible-community/antsibull-docs/blob/main/sphinx_antsibull_ext/src/antsibull-minimal.scss) using [SASS](https://sass-lang.com/) and [postcss](https://postcss.org/) using [autoprefixer](https://github.com/postcss/autoprefixer) and [cssnano](https://cssnano.co/).
+
+Use the script `build.sh` in `sphinx_antsibull_ext/css/` to build the `.css` file from the `.scss` file:
+
+```console
+cd sphinx_antsibull_ext/css/
+./build-css.sh
+```
+
+For this to work, you need to make sure that `sassc` and `postcss` are on your path and that the autoprefixer and nanocss modules are installed:
+
+```console
+# Debian:
+apt-get install sassc
+
+# PostCSS, autoprefixer and cssnano require nodejs/npm:
+npm install -g autoprefixer cssnano postcss postcss-cli
+```
+
 ## Creating a new release:
 
 1. Run `nox -e bump -- <version> <release_summary_message>`. This:

changelogs/config.yaml

@@ -3,7 +3,7 @@
 # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-changelog_filename_template: ../CHANGELOG.rst
+changelog_filename_template: ../CHANGELOG
 changelog_filename_version_depth: 0
 changes_file: changelog.yaml
 changes_format: combined
@@ -12,6 +12,9 @@ keep_fragments: false
 mention_ancestor: true
 new_plugins_after_name: removed_features
 notesdir: fragments
+output_formats:
+- md
+- rst
 prelude_section_name: release_summary
 prelude_section_title: Release Summary
 sections:

noxfile.py

@@ -236,20 +236,21 @@ def bump(session: nox.Session):
                 f"Either {fragment_file} must already exist, "
                 "or two positional arguments must be provided."
             )
-    install(session, "antsibull-changelog", "hatch")
+    # Needs newer antsibull-changelog for hatch version auto-detection support
+    install(session, "antsibull-changelog[toml] >= 0.24.0", "hatch")
     current_version = session.run("hatch", "version", silent=True).strip()
     if version != current_version:
         session.run("hatch", "version", version)
     if len(session.posargs) > 1:
         fragment = session.run(
             "python",
             "-c",
-            "import yaml ; "
-            f"print(yaml.dump(dict(release_summary={repr(session.posargs[1])})))",
+            "import sys, yaml ; "
+            f"yaml.dump(dict(release_summary={repr(session.posargs[1])}), sys.stdout)",
             silent=True,
         )
         with open(fragment_file, "w") as fp:
-            print(fragment, file=fp)
+            fp.write(fragment)
         session.run(
             "git",
             "add",
@@ -258,10 +259,11 @@ def bump(session: nox.Session):
             external=True,
         )
         session.run("git", "commit", "-m", f"Prepare {version}.", external=True)
-    session.run("antsibull-changelog", "release", "--version", version)
+    session.run("antsibull-changelog", "release")
     session.run(
         "git",
         "add",
+        "CHANGELOG.md",
         "CHANGELOG.rst",
         "changelogs/changelog.yaml",
         "changelogs/fragments/",

pyproject.toml

@@ -60,9 +60,11 @@ name = "Maxwell G"
 email = "maxwell@gtmx.me"
 
 [project.urls]
+"Documentation" = "https://ansible.readthedocs.io/projects/antsibull-docs/"
 "Source code" = "https://github.com/ansible-community/antsibull-docs"
 "Code of Conduct" = "https://docs.ansible.com/ansible/latest/community/code_of_conduct.html"
 "Bug tracker" = "https://github.com/ansible-community/antsibull-docs/issues"
+"Changelog" = "https://github.com/ansible-community/antsibull-docs/tree/main/CHANGELOG.md"
 
 [project.scripts]
 antsibull-docs = "antsibull_docs.cli.antsibull_docs:main"