Start writing the release notes in markdown.

Signed-off-by: Pedro Algarvio <palgarvio@vmware.com>

doc/conf.py

@@ -151,7 +151,8 @@ extensions = [
     "sphinx.ext.intersphinx",
     "httpdomain",
     "youtube",
-    "saltrepo"
+    "saltrepo",
+    "myst_parser",
     #'saltautodoc', # Must be AFTER autodoc
     #'shorturls',
 ]
@@ -215,6 +216,7 @@ extlinks = {
     "formula_url": ("https://github.com/saltstack-formulas/%s", "url %s"),
 }
 
+myst_gfm_only = True
 
 # ----- Localization -------------------------------------------------------->
 locale_dirs = ["locale/"]

doc/topics/releases/3006.0.md

@@ -0,0 +1,57 @@
+[](#release-3006.0)
+
+# Salt 3006.0 release notes - Codename Sulfur - UNRELEASED
+
+## Onedir packaging
+
+Going forward from the 3006.0 release, the Salt Project will only provide onedir
+packages to install or upgrade Salt. The classic, non-onedir packages will not
+be provided for supported operating systems. See [Upgrade to onedir](https://docs.saltproject.io/salt/install-guide/en/latest/topics/upgrade-to-onedir.html)
+in the [Salt Install Guide](https://docs.saltproject.io/salt/install-guide/en/latest) for information about upgrading from the classic packages to the onedir
+packages.
+
+
+## Dropping support for Python 3.5 and 3.6
+
+Python 3.5 and 3.6 will no longer be supported by Salt since they
+are end of life. Going forward our policy will be to align with Python's
+supported versions. See [Salt support for Python versions](https://docs.saltproject.io/salt/install-guide/en/latest/topics/salt-python-version-support.html)
+for more information.
+
+
+## All salt-api functionality disabled by default
+
+All netapi clients, which provide the functionality to ``salt-api``, will now
+be disabled by default as a security precaution. If you use ``salt-api``, you
+must add the new ``netapi_enable_clients`` option to your salt master config.  
+This is a breaking change and the ``salt-api`` will not function without this
+new configuration option. See [Enabling netapi client interfaces](https://docs.saltproject.io/en/3006.0/topics/netapi/netapi-enable-clients.html#netapi-enable-clients)
+for more information.
+
+
+## How do I migrate to the onedir packages?
+
+The migration path from the classic, non-onedir packages to the onedir packages
+will include:
+
+* Repo File: You need to update your repo file to point to the new repo paths
+  for your platform. After the repo file is updated, upgrade your Salt packages.  
+* Pip packages: You need to ensure any 3rd party pip packages are installed in
+  the correct onedir path. This can be accomplished in two ways:
+
+  * ``salt-pip install <package name>``
+  * Using the ``pip.installed`` Salt state.
+
+To install python packages into the system python environment, user's must now
+provide the ``pip_bin`` or ``bin_env`` to the pip state module.  
+
+For example:
+
+```yaml
+lib-foo:
+  pip.installed:
+    - pip_bin: /usr/bin/pip3
+lib-bar:
+  pip.installed:
+    - bin_env: /usr/bin/python3
+```

doc/topics/releases/3006.0.rst

@@ -1,67 +0,0 @@
-.. _release-3006.0:
-
-===========================================
-Salt 3006.0 release notes - Codename Sulfur
-===========================================
-
-Salt 3006.0 is currently under development.
-
-
-Onedir packaging
-----------------
-Going forward from the 3006.0 release, the Salt Project will only provide onedir
-packages to install or upgrade Salt. The classic, non-onedir packages will not
-be provided for supported operating systems. See
-`Upgrade to onedir <https://docs.saltproject.io/salt/install-guide/en/latest/topics/upgrade-to-onedir.html>`_
-in the `Salt Install Guide <https://docs.saltproject.io/salt/install-guide/en/latest/#>`_
-for information about upgrading from the classic packages to the onedir
-packages.
-
-
-Dropping support for Python 3.5 and 3.6
----------------------------------------
-
-Python 3.5 and 3.6 will no longer be supported by Salt since they
-are end of life. Going forward our policy will be to align with Python's
-supported versions. See
-`Salt support for Python versions <https://docs.saltproject.io/salt/install-guide/en/latest/topics/salt-python-version-support.html>`_
-for more information.
-
-
-All salt-api functionality disabled by default
-----------------------------------------------
-
-All netapi clients, which provide the functionality to ``salt-api``, will now
-be disabled by default as a security precaution. If you use ``salt-api``, you
-must add the new ``netapi_enable_clients`` option to your salt master config.
-This is a breaking change and the ``salt-api`` will not function without this
-new configuration option. See :ref:`netapi-enable-clients` for more
-information.
-
-
-How do I migrate to the onedir packages?
-----------------------------------------
-The migration path from the classic, non-onedir packages to the onedir packages
-will include:
-
-* Repo File: You need to update your repo file to point to the new repo paths
-  for your platform. After the repo file is updated, upgrade your Salt packages.
-* Pip packages: You need to ensure any 3rd party pip packages are installed in
-  the correct onedir path. This can be accomplished in two ways:
-
-  * ``salt-pip install <package name>``
-  * Using the ``pip.installed`` Salt state.
-
-To install python packages into the system python environment, user's must now
-provide the ``pip_bin`` or ``bin_env`` to the pip state module.
-
-For example:
-
-.. code-block:: yaml
-
-    lib-foo:
-      pip.installed:
-        - pip_bin: /usr/bin/pip3
-    lib-bar:
-      pip.installed:
-        - bin_env: /usr/bin/python3

requirements/static/ci/docs.in

@@ -2,3 +2,4 @@
 
 sphinx>=3.5.1; python_version < '3.9'
 sphinx>=6.1.0; python_version >= '3.9'
+myst-docutils[linkify]

requirements/static/ci/py3.10/docs.txt

@@ -40,24 +40,37 @@ jinja2==3.1.2
     # via
     #   -c requirements/static/ci/py3.10/linux.txt
     #   -r requirements/base.txt
+    #   myst-docutils
     #   sphinx
 jmespath==1.0.1
     # via
     #   -c requirements/static/ci/py3.10/linux.txt
     #   -r requirements/base.txt
+linkify-it-py==1.0.3
+    # via myst-docutils
 looseversion==1.0.2
     # via
     #   -c requirements/static/ci/py3.10/linux.txt
     #   -r requirements/base.txt
+markdown-it-py==2.1.0
+    # via
+    #   mdit-py-plugins
+    #   myst-docutils
 markupsafe==2.0.1
     # via
     #   -c requirements/static/ci/py3.10/linux.txt
     #   -r requirements/base.txt
     #   jinja2
+mdit-py-plugins==0.3.3
+    # via myst-docutils
+mdurl==0.1.2
+    # via markdown-it-py
 msgpack==1.0.2
     # via
     #   -c requirements/static/ci/py3.10/linux.txt
     #   -r requirements/base.txt
+myst-docutils[linkify]==0.18.1
+    # via -r requirements/static/ci/docs.in
 packaging==22.0
     # via
     #   -c requirements/static/ci/py3.10/linux.txt
@@ -81,6 +94,7 @@ pyyaml==5.4.1
     # via
     #   -c requirements/static/ci/py3.10/linux.txt
     #   -r requirements/base.txt
+    #   myst-docutils
 pyzmq==23.2.0
     # via
     #   -c requirements/static/ci/py3.10/linux.txt
@@ -106,6 +120,12 @@ sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
+typing-extensions==4.2.0
+    # via
+    #   -c requirements/static/ci/py3.10/linux.txt
+    #   myst-docutils
+uc-micro-py==1.0.1
+    # via linkify-it-py
 urllib3==1.26.6
     # via
     #   -c requirements/static/ci/py3.10/linux.txt

requirements/static/ci/py3.6/docs.txt

@@ -6,6 +6,10 @@
 #
 alabaster==0.7.12
     # via sphinx
+attrs==20.3.0
+    # via
+    #   -c requirements/static/ci/py3.6/linux.txt
+    #   markdown-it-py
 babel==2.9.1
     # via sphinx
 certifi==2022.12.7
@@ -40,24 +44,37 @@ jinja2==3.0.3
     # via
     #   -c requirements/static/ci/py3.6/linux.txt
     #   -r requirements/base.txt
+    #   myst-docutils
     #   sphinx
 jmespath==0.10.0
     # via
     #   -c requirements/static/ci/py3.6/linux.txt
     #   -r requirements/base.txt
+linkify-it-py==1.0.3
+    # via myst-docutils
 looseversion==1.0.3
     # via
     #   -c requirements/static/ci/py3.6/linux.txt
     #   -r requirements/base.txt
+markdown-it-py==2.0.1
+    # via
+    #   mdit-py-plugins
+    #   myst-docutils
 markupsafe==2.0.1
     # via
     #   -c requirements/static/ci/py3.6/linux.txt
     #   -r requirements/base.txt
     #   jinja2
+mdit-py-plugins==0.3.0
+    # via myst-docutils
+mdurl==0.1.0
+    # via markdown-it-py
 msgpack==1.0.2
     # via
     #   -c requirements/static/ci/py3.6/linux.txt
     #   -r requirements/base.txt
+myst-docutils[linkify]==0.16.1
+    # via -r requirements/static/ci/docs.in
 packaging==21.3
     # via
     #   -c requirements/static/ci/py3.6/linux.txt
@@ -85,6 +102,7 @@ pyyaml==5.4.1
     # via
     #   -c requirements/static/ci/py3.6/linux.txt
     #   -r requirements/base.txt
+    #   myst-docutils
 pyzmq==23.2.0
     # via
     #   -c requirements/static/ci/py3.6/linux.txt
@@ -110,6 +128,12 @@ sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.4
     # via sphinx
+typing-extensions==3.10.0.0
+    # via
+    #   -c requirements/static/ci/py3.6/linux.txt
+    #   markdown-it-py
+uc-micro-py==1.0.1
+    # via linkify-it-py
 urllib3==1.26.6
     # via
     #   -c requirements/static/ci/py3.6/linux.txt

requirements/static/ci/py3.7/docs.txt

@@ -40,24 +40,37 @@ jinja2==3.1.2
     # via
     #   -c requirements/static/ci/py3.7/linux.txt
     #   -r requirements/base.txt
+    #   myst-docutils
     #   sphinx
 jmespath==1.0.1
     # via
     #   -c requirements/static/ci/py3.7/linux.txt
     #   -r requirements/base.txt
+linkify-it-py==1.0.3
+    # via myst-docutils
 looseversion==1.0.2
     # via
     #   -c requirements/static/ci/py3.7/linux.txt
     #   -r requirements/base.txt
+markdown-it-py==2.1.0
+    # via
+    #   mdit-py-plugins
+    #   myst-docutils
 markupsafe==2.0.1
     # via
     #   -c requirements/static/ci/py3.7/linux.txt
     #   -r requirements/base.txt
     #   jinja2
+mdit-py-plugins==0.3.3
+    # via myst-docutils
+mdurl==0.1.2
+    # via markdown-it-py
 msgpack==1.0.2
     # via
     #   -c requirements/static/ci/py3.7/linux.txt
     #   -r requirements/base.txt
+myst-docutils[linkify]==0.18.1
+    # via -r requirements/static/ci/docs.in
 packaging==21.3
     # via
     #   -c requirements/static/ci/py3.7/linux.txt
@@ -85,6 +98,7 @@ pyyaml==5.4.1
     # via
     #   -c requirements/static/ci/py3.7/linux.txt
     #   -r requirements/base.txt
+    #   myst-docutils
 pyzmq==23.2.0
     # via
     #   -c requirements/static/ci/py3.7/linux.txt
@@ -110,6 +124,13 @@ sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.4
     # via sphinx
+typing-extensions==3.10.0.0
+    # via
+    #   -c requirements/static/ci/py3.7/linux.txt
+    #   markdown-it-py
+    #   myst-docutils
+uc-micro-py==1.0.1
+    # via linkify-it-py
 urllib3==1.26.6
     # via
     #   -c requirements/static/ci/py3.7/linux.txt

requirements/static/ci/py3.8/docs.txt

@@ -40,24 +40,37 @@ jinja2==3.1.2
     # via
     #   -c requirements/static/ci/py3.8/linux.txt
     #   -r requirements/base.txt
+    #   myst-docutils
     #   sphinx
 jmespath==1.0.1
     # via
     #   -c requirements/static/ci/py3.8/linux.txt
     #   -r requirements/base.txt
+linkify-it-py==1.0.3
+    # via myst-docutils
 looseversion==1.0.2
     # via
     #   -c requirements/static/ci/py3.8/linux.txt
     #   -r requirements/base.txt
+markdown-it-py==2.1.0
+    # via
+    #   mdit-py-plugins
+    #   myst-docutils
 markupsafe==2.0.1
     # via
     #   -c requirements/static/ci/py3.8/linux.txt
     #   -r requirements/base.txt
     #   jinja2
+mdit-py-plugins==0.3.3
+    # via myst-docutils
+mdurl==0.1.2
+    # via markdown-it-py
 msgpack==1.0.2
     # via
     #   -c requirements/static/ci/py3.8/linux.txt
     #   -r requirements/base.txt
+myst-docutils[linkify]==0.18.1
+    # via -r requirements/static/ci/docs.in
 packaging==22.0
     # via
     #   -c requirements/static/ci/py3.8/linux.txt
@@ -81,6 +94,7 @@ pyyaml==5.4.1
     # via
     #   -c requirements/static/ci/py3.8/linux.txt
     #   -r requirements/base.txt
+    #   myst-docutils
 pyzmq==23.2.0
     # via
     #   -c requirements/static/ci/py3.8/linux.txt
@@ -106,6 +120,12 @@ sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.4
     # via sphinx
+typing-extensions==4.2.0
+    # via
+    #   -c requirements/static/ci/py3.8/linux.txt
+    #   myst-docutils
+uc-micro-py==1.0.1
+    # via linkify-it-py
 urllib3==1.26.6
     # via
     #   -c requirements/static/ci/py3.8/linux.txt

requirements/static/ci/py3.9/docs.txt

@@ -44,24 +44,37 @@ jinja2==3.1.2
     # via
     #   -c requirements/static/ci/py3.9/linux.txt
     #   -r requirements/base.txt
+    #   myst-docutils
     #   sphinx
 jmespath==1.0.1
     # via
     #   -c requirements/static/ci/py3.9/linux.txt
     #   -r requirements/base.txt
+linkify-it-py==1.0.3
+    # via myst-docutils
 looseversion==1.0.2
     # via
     #   -c requirements/static/ci/py3.9/linux.txt
     #   -r requirements/base.txt
+markdown-it-py==2.1.0
+    # via
+    #   mdit-py-plugins
+    #   myst-docutils
 markupsafe==2.0.1
     # via
     #   -c requirements/static/ci/py3.9/linux.txt
     #   -r requirements/base.txt
     #   jinja2
+mdit-py-plugins==0.3.3
+    # via myst-docutils
+mdurl==0.1.2
+    # via markdown-it-py
 msgpack==1.0.2
     # via
     #   -c requirements/static/ci/py3.9/linux.txt
     #   -r requirements/base.txt
+myst-docutils[linkify]==0.18.1
+    # via -r requirements/static/ci/docs.in
 packaging==22.0
     # via
     #   -c requirements/static/ci/py3.9/linux.txt
@@ -85,6 +98,7 @@ pyyaml==5.4.1
     # via
     #   -c requirements/static/ci/py3.9/linux.txt
     #   -r requirements/base.txt
+    #   myst-docutils
 pyzmq==23.2.0
     # via
     #   -c requirements/static/ci/py3.9/linux.txt
@@ -110,6 +124,12 @@ sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
+typing-extensions==4.2.0
+    # via
+    #   -c requirements/static/ci/py3.9/linux.txt
+    #   myst-docutils
+uc-micro-py==1.0.1
+    # via linkify-it-py
 urllib3==1.26.6
     # via
     #   -c requirements/static/ci/py3.9/linux.txt

tools/changelog.py

@@ -348,14 +348,15 @@ def update_release_notes(ctx: Context, salt_version: str, draft: bool = False):
         major_version = salt_version
     changes = _get_changelog_contents(ctx, salt_version)
     changes = "\n".join(changes.split("\n")[2:])
-    tmpnotes = f"doc/topics/releases/{salt_version}.rst.tmp"
+    tmpnotes = f"doc/topics/releases/{salt_version}.md.tmp"
     try:
-        with open(f"doc/topics/releases/{major_version}.rst") as rfp:
+        with open(f"doc/topics/releases/{major_version}.md") as rfp:
             existing = rfp.read()
     except FileNotFoundError:
         existing = ""
     with open(tmpnotes, "w") as wfp:
         wfp.write(existing)
+        wfp.write("\n## Changelog\n")
         wfp.write(changes)
     try:
         with open(tmpnotes) as rfp:
@@ -363,7 +364,7 @@ def update_release_notes(ctx: Context, salt_version: str, draft: bool = False):
             if draft:
                 ctx.print(contents, soft_wrap=True)
             else:
-                with open(f"doc/topics/releases/{salt_version}.rst", "w") as wfp:
+                with open(f"doc/topics/releases/{salt_version}.md", "w") as wfp:
                     wfp.write(contents)
     finally:
         os.remove(tmpnotes)