chore: enhance doc-changelog migration guide

doc/source/migrations/docs-changelog-setup.rst

@@ -3,25 +3,154 @@
 Doc-changelog action setup
 ==========================
 
-To set up your repository to use the ``ansys/actions/doc-changelog`` action, see
-`changelog implementation in PyAnsys-Geometry <https://github.com/ansys/pyansys-geometry/pull/1023/files>`_
-or follow these steps:
+The release notes for your project can either be in your documentation or the ``CHANGELOG.md`` file.
+Follow the instructions in the `update the workflow <#update-the-workflow>`_ section to add the ``ansys/actions/doc-changelog`` action
+to your workflow, and then choose between adding the release notes in your documentation
+or the ``CHANGELOG.md`` file.
 
+Update the workflow
+-------------------
 
-1. Add the following lines to the ``pyproject.toml`` file, replacing ``{repo-name}`` with the name of the repository. For example, ``pyansys-geometry``.
+Update the ``.github/workflows/label.yml`` file to use the changelog action.
+
+Change the ``pull_request`` trigger at the top of the preceding ``.yml`` file so that it lists the pull request actions that cause the workflows to run:
+
+.. code:: yaml
+
+    on:
+    pull_request:
+        # opened, reopened, and synchronize are default for pull_request
+        # edited - when PR title or body is changed
+        # labeled - when labels are added to PR
+        types: [opened, reopened, synchronize, edited, labeled]
+
+At the end of the ``.github/workflows/label.yml`` file, add the following lines for the changelog action:
+
+.. code:: yaml
+
+    changelog-fragment:
+        name: "Create changelog fragment"
+        needs: [labeler]
+        permissions:
+          contents: write
+          pull-requests: write
+        runs-on: ubuntu-latest
+        steps:
+        - uses: ansys/actions/doc-changelog@{{ version }}
+          with:
+            token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }}
+
+|
+
+Next, follow the instructions to create release notes in your `documentation <#include-the-release-notes-in-your-documentation>`_ or `CHANGELOG.md file <#include-the-release-notes-in-changelog-md>`_ depending on your preference.
+
+Include the release notes in your documentation
+-----------------------------------------------
+
+1. Create the ``doc/changelog.d`` directory and then within it add a file named ``changelog_template.jinja`` that contains the following lines:
+
+.. code:: jinja
+
+    {% if sections[""] %}
+    {% for category, val in definitions.items() if category in sections[""] %}
+
+    {{ definitions[category]['name'] }}
+    {% set underline = '^' * definitions[category]['name']|length %}
+    {{ underline }}
+
+    {% for text, values in sections[""][category].items() %}
+    - {{ text }} {{ values|join(', ') }}
+    {% endfor %}
+
+    {% endfor %}
+    {% else %}
+    No significant changes.
+
+
+    {% endif %}
+
+|
+
+2. Create a new file named ``changelog.rst`` in the ``doc/source`` directory. Add the following lines to the file:
+
+.. code:: rst
+
+    .. _ref_release_notes:
+
+    Release notes
+    #############
+
+    This document contains the release notes for the project.
+
+    .. vale off
+
+    .. towncrier release notes start
+
+
+    .. vale on
+
+.. note::
+
+    If your project previously used ``CHANGELOG.md`` to record the release notes, change the description under "Release notes," replacing ``{org-name}`` and ``{repo-name}`` with the name of the organization and repository respectively, and ``{latest-version}`` with the most recent version in your ``CHANGELOG.md`` file:
+
+    .. code:: rst
+
+        This document contains the release notes for the project. See release notes for v{latest-version} and earlier
+        in `CHANGELOG.md <https://github.com/{org-name}/{repo-name}/blob/main/CHANGELOG.md>`_.
+
+|
+
+3. Add ``changelog`` to the toctree list in the ``doc/source/index.rst`` file. ``changelog`` is placed last in the ``toctree`` list, so the "Release notes" tab is last in the documentation.
+
+.. code:: rst
+
+    .. toctree::
+       :hidden:
+       :maxdepth: 3
+
+       <other files>
+       changelog
+
+|
+
+4. Add the following lines to the ``doc/source/conf.py`` file, replacing ``{org-name}`` and ``{repo-name}`` with the name of the organization and repository respectively:
+
+.. code:: python
+
+    # If we are on a release, we have to ignore the "release" URLs, since it is not
+    # available until the release is published.
+    if switcher_version != "dev":
+        linkcheck_ignore.append(
+            f"https://github.com/{org-name}/{repo-name}/releases/tag/v{__version__}"
+        )
+
+.. note::
+
+  This assumes the following code already exists in the ``doc/source/conf.py`` file:
+
+  .. code:: python
+
+      from ansys_sphinx_theme import get_version_match
+      from ansys.<product>.<library> import __version__
+
+      release = version = __version__
+      switcher_version = get_version_match(version)
+
+|
+
+5. Add the following lines to the ``pyproject.toml`` file, replacing ``{org-name}`` and ``{repo-name}`` with the name of the organization and repository respectively.
 Also, replace ``ansys.<product>.<library>`` with the name under ``tool.flit.module``. For example, ``ansys.geometry.core``.
 
 .. code:: toml
 
     [tool.towncrier]
     package = "ansys.<product>.<library>"
     directory = "doc/changelog.d"
-    filename = "CHANGELOG.md"
-    start_string = "<!-- towncrier release notes start -->\n"
-    underlines = ["", "", ""]
+    filename = "doc/source/changelog.rst"
+    start_string = ".. towncrier release notes start\n"
     template = "doc/changelog.d/changelog_template.jinja"
-    title_format = "## [{version}](https://github.com/ansys/{repo-name}/releases/tag/v{version}) - {project_date}"
-    issue_format = "[#{issue}](https://github.com/ansys/{repo-name}/pull/{issue})"
+    title_format = "`{version} <https://github.com/{org-name}/{repo-name}/releases/tag/v{version}>`_ - {project_date}"
+    issue_format = "`#{issue} <https://github.com/{org-name}/{repo-name}/pull/{issue}>`_"
 
     [[tool.towncrier.type]]
     directory = "added"
@@ -48,9 +177,28 @@ Also, replace ``ansys.<product>.<library>`` with the name under ``tool.flit.modu
     name = "Miscellaneous"
     showcontent = true
 
+.. note::
+
+    If empty, the previous ``CHANGELOG.md`` file can be removed from the repository, as the changelog is now part of the documentation.
+
+    However, if the ``CHANGELOG.md`` file is kept, it can be adapted to include the link to the documentation changelog.
+
+    For example, the ``CHANGELOG.md`` file could look like this:
+
+    .. code:: md
+
+        This project uses [towncrier](https://towncrier.readthedocs.io/). Changes for the upcoming release can be found in
+        [changelog.rst](doc/source/changelog.rst).
+
 |
 
-2. Create the ``doc/changelog.d`` directory and then within it add a file named ``changelog_template.jinja`` that contains the following lines:
+Reference pull requests for the changes can be found in the `PyAnsys Geometry <https://github.com/ansys/pyansys-geometry/pull/1138>`_ and `PyMechanical <https://github.com/ansys/pymechanical/pull/757/files>`_ repositories.
+The PyAnsys-Geometry pull request includes some other changes, but the changelog implementation is the same as described in this document.
+
+Include the release notes in ``CHANGELOG.md``
+---------------------------------------------
+
+1. Create the ``doc/changelog.d`` directory and then within it add a file named ``changelog_template.jinja`` that contains the following lines:
 
 .. code:: jinja
 
@@ -72,11 +220,11 @@ Also, replace ``ansys.<product>.<library>`` with the name under ``tool.flit.modu
 
 |
 
-3. Add the following lines to the ``CHANGELOG.md`` file, replacing ``{repo-name}`` with the name of the repository:
+2. Add the following lines to the ``CHANGELOG.md`` file, replacing ``{org-name}`` and ``{repo-name}`` with the name of the organization and repository respectively:
 
 .. code:: md
 
-    This project uses [towncrier](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in <https://github.com/ansys/{repo-name}/tree/main/doc/changelog.d/>.
+    This project uses [towncrier](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in <https://github.com/{org-name}/{repo-name}/tree/main/doc/changelog.d/>.
 
     <!-- towncrier release notes start -->
 
@@ -94,116 +242,50 @@ Also, replace ``ansys.<product>.<library>`` with the name under ``tool.flit.modu
 
 |
 
-4. Update the ``.github/workflows/label.yml`` file to use the changelog action.
-
-Change the ``pull_request`` trigger at the top of the preceding ``.yml`` file so that it lists the pull request actions that cause the workflows to run:
-
-.. code:: yaml
-
-    on:
-    pull_request:
-        # opened, reopened, and synchronize are default for pull_request
-        # edited - when PR title or body is changed
-        # labeled - when labels are added to PR
-        types: [opened, reopened, synchronize, edited, labeled]
-
-At the end of the ``.github/workflows/label.yml`` file, add the following lines for the changelog action:
-
-.. code:: yaml
-
-    changelog-fragment:
-        name: "Create changelog fragment"
-        needs: [labeler]
-        permissions:
-          contents: write
-          pull-requests: write
-        runs-on: ubuntu-latest
-        steps:
-        - uses: ansys/actions/doc-changelog@{{ version }}
-          with:
-            token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }}
-
-
-Implementing the changelog as part of your documentation
---------------------------------------------------------
-
-The previous steps set up the changelog for your repository. To implement the changelog in your documentation,
-some modifications have to be performed. Based on the PyAnsys libraries standards, this section assumes that
-the repository has a ``docs`` directory with a Sphinx documentation setup.
-
-1. Create a new file named ``changelog.rst`` in the ``docs`` directory. Add the following lines to the file:
-
-.. code:: rst
-
-    .. _ref_release_notes:
-
-    Release notes
-    #############
-
-    This document contains the release notes for the project.
-
-    .. vale off
-
-    .. towncrier release notes start
-
-
-    .. vale on
-
-2. Add the ``changelog.rst`` file to the ``index.rst`` file in the ``docs`` directory.
-
-.. code:: rst
-
-    .. toctree::
-       :hidden:
-       :maxdepth: 3
-
-       changelog
-       <other files>
-
-
-3. Add the following lines to the ``conf.py`` file in the ``docs`` directory, replacing ``{repo-name}``
-   and ``{org-name}`` with the name of the repository:
-
-.. code:: python
-
-    # If we are on a release, we have to ignore the "release" URLs, since it is not
-    # available until the release is published.
-    if switcher_version != "dev":
-        linkcheck_ignore.append(
-            f"https://github.com/{org-name}/{repo-name}/releases/tag/v{__version__}"
-        )
-
-4. Modify the ``pyproject.toml`` file to include the following lines, replacing ``{repo-name}``
-   and ``{org-name}`` with the name of the repository:
+3. Add the following lines to the ``pyproject.toml`` file, replacing ``{org-name}`` and ``{repo-name}`` with the name of the organization and repository respectively.
+Also, replace ``ansys.<product>.<library>`` with the name under ``tool.flit.module``. For example, ``ansys.geometry.core``.
 
 .. code:: toml
 
     [tool.towncrier]
     package = "ansys.<product>.<library>"
     directory = "doc/changelog.d"
-    filename = "doc/source/changelog.rst"
-    start_string = ".. towncrier release notes start\n"
+    filename = "CHANGELOG.md"
+    start_string = "<!-- towncrier release notes start -->\n"
+    underlines = ["", "", ""]
     template = "doc/changelog.d/changelog_template.jinja"
-    title_format = "`{version} <https://github.com/{org-name}/{repo-name}/releases/tag/v{version}>`_ - {project_date}"
-    issue_format = "`#{issue} <https://github.com/{org-name}/{repo-name}/pull/{issue}>`_"
+    title_format = "## [{version}](https://github.com/ansys/{repo-name}/releases/tag/v{version}) - {project_date}"
+    issue_format = "[#{issue}](https://github.com/ansys/{repo-name}/pull/{issue})"
 
-.. note::
+    [[tool.towncrier.type]]
+    directory = "added"
+    name = "Added"
+    showcontent = true
 
-    The previous ``CHANGELOG.md`` file can be removed from the repository, as the changelog is now part of the documentation.
+    [[tool.towncrier.type]]
+    directory = "changed"
+    name = "Changed"
+    showcontent = true
 
-    However, if the ``CHANGELOG.md`` file is kept, it can be adapted to include the link to the documentation changelog.
+    [[tool.towncrier.type]]
+    directory = "fixed"
+    name = "Fixed"
+    showcontent = true
 
-    For example, the ``CHANGELOG.md`` file could look like this:
+    [[tool.towncrier.type]]
+    directory = "dependencies"
+    name = "Dependencies"
+    showcontent = true
 
-    .. code:: md
+    [[tool.towncrier.type]]
+    directory = "miscellaneous"
+    name = "Miscellaneous"
+    showcontent = true
 
-        This project uses [towncrier](https://towncrier.readthedocs.io/) and the
-        changes for the upcoming release can be found in
-        this [repository file](doc/changelog.d/changelog.rst).
+|
 
+A reference pull request for these changes can be found in the `PyAnsys-Geometry <https://github.com/ansys/pyansys-geometry/pull/1023/files>`_ repository.
 
-A reference pull request for the changes can be found in the `PyAnsys Geometry repository <https://github.com/ansys/pyansys-geometry/pull/1138>`_.
-This pull request includes some other changes, but the changelog implementation is the same as described in this document.
 
 ``towncrier`` commands
 ----------------------

doc/styles/config/vocabularies/ANSYS/accept.txt

@@ -5,6 +5,7 @@ dev
 GitHub
 pytest
 PyPI
+toctree
 towncrier
 TXT
 PyAnsys Dashboard