From c78faa387918ebd2bfaef86b5030e593bacb6ab8 Mon Sep 17 00:00:00 2001 From: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com> Date: Fri, 19 Apr 2024 08:58:35 +0200 Subject: [PATCH 1/4] docs: implementing changelog as part of the documentation --- .../migrations/docs-changelog-setup.rst | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/doc/source/migrations/docs-changelog-setup.rst b/doc/source/migrations/docs-changelog-setup.rst index f1dd238f0..a3bc86505 100644 --- a/doc/source/migrations/docs-changelog-setup.rst +++ b/doc/source/migrations/docs-changelog-setup.rst @@ -124,6 +124,87 @@ At the end of the ``.github/workflows/label.yml`` file, add the following lines token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }} +Implemeting 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 + +2. Add the ``changelog.rst`` file to the ``index.rst`` file in the ``docs`` directory. + +.. code:: rst + + .. toctree:: + :hidden: + :maxdepth: 3 + + changelog + + + +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( + rf"https://github.com/{org_name}/{repo_name}/releases/download/v{__version__}/.*" + ) + 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: + +.. code:: toml + + [tool.towncrier] + package = "ansys.." + directory = "doc/changelog.d" + filename = "doc/source/changelog.rst" + start_string = ".. towncrier release notes start\n" + template = "doc/changelog.d/changelog_template.jinja" + title_format = "`{version} `_ - {project_date}" + issue_format = "`#{issue} `_" + +.. note:: + + 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/) and the + changes for the upcoming release can be found in + this [repository file](doc/changelog.d/changelog.rst). + + +A reference pull request for the changes can be found in the `PyAnsys Geometry repository `_. +This pull request includes some other changes, but the changelog implementation is the same as described in this document. + ``towncrier`` commands ---------------------- From 52ab0f4c1092d2ad7a7965ad0d834249820de6b6 Mon Sep 17 00:00:00 2001 From: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com> Date: Fri, 19 Apr 2024 09:06:29 +0200 Subject: [PATCH 2/4] Apply suggestions from code review --- doc/source/migrations/docs-changelog-setup.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/migrations/docs-changelog-setup.rst b/doc/source/migrations/docs-changelog-setup.rst index a3bc86505..e95a31632 100644 --- a/doc/source/migrations/docs-changelog-setup.rst +++ b/doc/source/migrations/docs-changelog-setup.rst @@ -159,7 +159,7 @@ the repository has a ``docs`` directory with a Sphinx documentation setup. 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: + and ``{org-name}`` with the name of the repository: .. code:: python @@ -167,14 +167,14 @@ the repository has a ``docs`` directory with a Sphinx documentation setup. # available until the release is published. if switcher_version != "dev": linkcheck_ignore.append( - rf"https://github.com/{org_name}/{repo_name}/releases/download/v{__version__}/.*" + rf"https://github.com/{org-name}/{repo-name}/releases/download/v{__version__}/.*" ) linkcheck_ignore.append( - f"https://github.com/{org_name}/{repo_name}/releases/tag/v{__version__}" + 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: + and ``{org-name}`` with the name of the repository: .. code:: toml @@ -184,8 +184,8 @@ the repository has a ``docs`` directory with a Sphinx documentation setup. filename = "doc/source/changelog.rst" start_string = ".. towncrier release notes start\n" template = "doc/changelog.d/changelog_template.jinja" - title_format = "`{version} `_ - {project_date}" - issue_format = "`#{issue} `_" + title_format = "`{version} `_ - {project_date}" + issue_format = "`#{issue} `_" .. note:: From cfaa08dd506876ce0379daff6b2b0596503d54fd Mon Sep 17 00:00:00 2001 From: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com> Date: Fri, 19 Apr 2024 09:07:11 +0200 Subject: [PATCH 3/4] Update doc/source/migrations/docs-changelog-setup.rst --- doc/source/migrations/docs-changelog-setup.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/doc/source/migrations/docs-changelog-setup.rst b/doc/source/migrations/docs-changelog-setup.rst index e95a31632..fe32031d7 100644 --- a/doc/source/migrations/docs-changelog-setup.rst +++ b/doc/source/migrations/docs-changelog-setup.rst @@ -166,9 +166,6 @@ the repository has a ``docs`` directory with a Sphinx documentation setup. # 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( - rf"https://github.com/{org-name}/{repo-name}/releases/download/v{__version__}/.*" - ) linkcheck_ignore.append( f"https://github.com/{org-name}/{repo-name}/releases/tag/v{__version__}" ) From 1cf14d8bc7c810b9f0d4666f1409648e28f72a4f Mon Sep 17 00:00:00 2001 From: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com> Date: Fri, 19 Apr 2024 09:09:29 +0200 Subject: [PATCH 4/4] fix: vale issue --- doc/source/migrations/docs-changelog-setup.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/migrations/docs-changelog-setup.rst b/doc/source/migrations/docs-changelog-setup.rst index fe32031d7..2717da3a6 100644 --- a/doc/source/migrations/docs-changelog-setup.rst +++ b/doc/source/migrations/docs-changelog-setup.rst @@ -124,8 +124,8 @@ At the end of the ``.github/workflows/label.yml`` file, add the following lines token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }} -Implemeting the changelog as part of your documentation -------------------------------------------------------- +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