docs: add release notes in our documentation (#1138)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: pyansys-ci-bot <[email protected]> Co-authored-by: Kathy Pippert <[email protected]>
ansys · Apr 19, 2024 · d5224da · d5224da
1 parent fdb38fc
commit d5224da
Show file tree

Hide file tree

Showing 9 changed files with 117 additions and 83 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,74 +1,7 @@
 # CHANGELOG
 
-This project uses [towncrier](https://towncrier.readthedocs.io/) to generate changelogs. You can see the changes for the upcoming release in the [changelog fragment directory](https://github.com/ansys/pyansys-geometry/tree/main/doc/changelog.d).
+This project uses [towncrier](https://towncrier.readthedocs.io/) to generate changelogs.
 
-<!-- towncrier release notes start -->
+Refer to the [raw release notes](doc/source/changelog.rst) for more information.
 
-## [0.5.0](https://github.com/ansys/pyansys-geometry/releases/tag/v0.5.0) - 2024-04-17
-
-
-### Added
-
-- feat: inserting document into existing design [#930](https://github.com/ansys/pyansys-geometry/pull/930)
-- feat: add changelog action [#1023](https://github.com/ansys/pyansys-geometry/pull/1023)
-- feat: create a sphere body on the backend [#1035](https://github.com/ansys/pyansys-geometry/pull/1035)
-- feat: mirror a body [#1055](https://github.com/ansys/pyansys-geometry/pull/1055)
-- feat: sweeping chains and profiles [#1056](https://github.com/ansys/pyansys-geometry/pull/1056)
-- feat: vulnerability checks [#1071](https://github.com/ansys/pyansys-geometry/pull/1071)
-- feat: loft profiles [#1075](https://github.com/ansys/pyansys-geometry/pull/1075)
-- feat: accept bandit advisories in-line for subprocess [#1077](https://github.com/ansys/pyansys-geometry/pull/1077)
-- feat: adding containers to automatic launcher [#1090](https://github.com/ansys/pyansys-geometry/pull/1090)
-- feat: minor changes to Linux Dockerfile [#1111](https://github.com/ansys/pyansys-geometry/pull/1111)
-- feat: avoid error if folder exists [#1125](https://github.com/ansys/pyansys-geometry/pull/1125)
-
-### Changed
-
-- build: changing sphinx-autoapi from 3.1.a2 to 3.1.a4 [#1038](https://github.com/ansys/pyansys-geometry/pull/1038)
-- chore: add pre-commit.ci configuration [#1065](https://github.com/ansys/pyansys-geometry/pull/1065)
-- chore: dependabot PR automatic approval [#1067](https://github.com/ansys/pyansys-geometry/pull/1067)
-- ci: bump the actions group with 1 update [#1082](https://github.com/ansys/pyansys-geometry/pull/1082)
-- chore: update docker tags to be kept [#1085](https://github.com/ansys/pyansys-geometry/pull/1085)
-- chore: update pre-commit versions [#1094](https://github.com/ansys/pyansys-geometry/pull/1094)
-- build: use ansys-sphinx-theme autoapi target [#1097](https://github.com/ansys/pyansys-geometry/pull/1097)
-- fix: removing @PipKat from *.md files - changelog fragments [#1098](https://github.com/ansys/pyansys-geometry/pull/1098)
-- ci: dashboard upload does not apply anymore [#1099](https://github.com/ansys/pyansys-geometry/pull/1099)
-- chore: pre-commit.ci not working properly [#1108](https://github.com/ansys/pyansys-geometry/pull/1108)
-- chore: update and adding pre-commit.ci config hook [#1109](https://github.com/ansys/pyansys-geometry/pull/1109)
-- ci: main Python version update to 3.12 [#1112](https://github.com/ansys/pyansys-geometry/pull/1112)
-- ci: skip Linux tests with common approach [#1113](https://github.com/ansys/pyansys-geometry/pull/1113)
-- ci: build changelog on release [#1118](https://github.com/ansys/pyansys-geometry/pull/1118)
-- chore: update CHANGELOG for v0.5.0 [#1119](https://github.com/ansys/pyansys-geometry/pull/1119)
-
-### Fixed
-
-- feat: re-enable open file on Linux [#817](https://github.com/ansys/pyansys-geometry/pull/817)
-- fix: adapt export and download tests to new hoops [#1057](https://github.com/ansys/pyansys-geometry/pull/1057)
-- fix: linux Dockerfile - replace .NET6.0 references by .NET8.0 [#1069](https://github.com/ansys/pyansys-geometry/pull/1069)
-- fix: misleading docstring for sweep_chain() [#1070](https://github.com/ansys/pyansys-geometry/pull/1070)
-- fix: prepare_and_start_backend is only available on Windows [#1076](https://github.com/ansys/pyansys-geometry/pull/1076)
-- fix: unit tests failing after dms update [#1087](https://github.com/ansys/pyansys-geometry/pull/1087)
-- build: beartype upper limit on v0.18 [#1095](https://github.com/ansys/pyansys-geometry/pull/1095)
-- fix: improper types being passed for Face and Edge ctor. [#1096](https://github.com/ansys/pyansys-geometry/pull/1096)
-- fix: return type should be dict and not ``ScalarMapContainer`` (grpc type) [#1103](https://github.com/ansys/pyansys-geometry/pull/1103)
-- fix: env version for Dockerfile Windows [#1120](https://github.com/ansys/pyansys-geometry/pull/1120)
-- fix: changelog description ill-formatted [#1121](https://github.com/ansys/pyansys-geometry/pull/1121)
-- fix: solve issues with intersphinx when releasing [#1123](https://github.com/ansys/pyansys-geometry/pull/1123)
-
-### Dependencies
-
-- build: bump the docs-deps group with 2 updates [#1062](https://github.com/ansys/pyansys-geometry/pull/1062), [#1093](https://github.com/ansys/pyansys-geometry/pull/1093), [#1105](https://github.com/ansys/pyansys-geometry/pull/1105)
-- build: bump ansys-api-geometry from 0.3.13 to 0.4.0 [#1066](https://github.com/ansys/pyansys-geometry/pull/1066)
-- build: bump the docs-deps group with 1 update [#1080](https://github.com/ansys/pyansys-geometry/pull/1080)
-- build: bump pytest-cov from 4.1.0 to 5.0.0 [#1081](https://github.com/ansys/pyansys-geometry/pull/1081)
-- build: bump ansys-api-geometry from 0.4.0 to 0.4.1 [#1092](https://github.com/ansys/pyansys-geometry/pull/1092)
-- build: bump beartype from 0.17.2 to 0.18.2 [#1106](https://github.com/ansys/pyansys-geometry/pull/1106)
-- build: bump ansys-tools-path from 0.4.1 to 0.5.1 [#1107](https://github.com/ansys/pyansys-geometry/pull/1107)
-- build: bump panel from 1.4.0 to 1.4.1 in the docs-deps group [#1114](https://github.com/ansys/pyansys-geometry/pull/1114)
-- build: bump scipy from 1.12.0 to 1.13.0 [#1115](https://github.com/ansys/pyansys-geometry/pull/1115)
-
-
-### Miscellaneous
-
-- [pre-commit.ci] pre-commit autoupdate [#1063](https://github.com/ansys/pyansys-geometry/pull/1063)
-- docs: add examples on new methods [#1089](https://github.com/ansys/pyansys-geometry/pull/1089)
-- chore: pre-commit automatic update [#1116](https://github.com/ansys/pyansys-geometry/pull/1116)
+[Published release notes](https://docs.pyansys.com/version/stable/changelog.html) can be found in the online documentation.
diff --git a/doc/changelog.d/1138.changed.md b/doc/changelog.d/1138.changed.md
@@ -0,0 +1 @@
+docs: add release notes in our documentation
diff --git a/doc/changelog.d/changelog_template.jinja b/doc/changelog.d/changelog_template.jinja
@@ -1,7 +1,9 @@
 {% if sections[""] %}
 {% for category, val in definitions.items() if category in sections[""] %}
 
-### {{ definitions[category]['name'] }}
+{{ definitions[category]['name'] }}
+{% set underline = '^' * definitions[category]['name']|length %}
+{{ underline }}
 
 {% for text, values in sections[""][category].items() %}
 - {{ text }} {{ values|join(', ') }}

diff --git a/doc/source/assets.rst b/doc/source/assets.rst
@@ -51,8 +51,8 @@ The following wheelhouse files are available for download:
 Geometry service Docker container assets
 ----------------------------------------
 
-Build the latest Geometry service Docker container using the following assets. Instructions
-on how to build the containers are found at `Docker containers <getting_started/docker/index.html>`_.
+Build the latest Geometry service Docker container using the following assets. For
+information on how to build the container, see :ref:`Docker containers <ref_docker>`.
 
 Currently, the Geometry service backend is mainly delivered as a **Windows** Docker container.
 However, these containers require a Windows machine to run them.

diff --git a/doc/source/changelog.rst b/doc/source/changelog.rst
@@ -0,0 +1,87 @@
+.. _ref_release_notes:
+
+Release notes
+#############
+
+This document contains the release notes for the PyAnsys Geometry project.
+
+.. vale off
+
+.. towncrier release notes start
+
+`0.5.0 <https://github.com/ansys/pyansys-geometry/releases/tag/v0.5.0>`_ - 2024-04-17
+=====================================================================================
+
+Added
+^^^^^
+
+- feat: inserting document into existing design `#930 <https://github.com/ansys/pyansys-geometry/pull/930>`_
+- feat: add changelog action `#1023 <https://github.com/ansys/pyansys-geometry/pull/1023>`_
+- feat: create a sphere body on the backend `#1035 <https://github.com/ansys/pyansys-geometry/pull/1035>`_
+- feat: mirror a body `#1055 <https://github.com/ansys/pyansys-geometry/pull/1055>`_
+- feat: sweeping chains and profiles `#1056 <https://github.com/ansys/pyansys-geometry/pull/1056>`_
+- feat: vulnerability checks `#1071 <https://github.com/ansys/pyansys-geometry/pull/1071>`_
+- feat: loft profiles `#1075 <https://github.com/ansys/pyansys-geometry/pull/1075>`_
+- feat: accept bandit advisories in-line for subprocess `#1077 <https://github.com/ansys/pyansys-geometry/pull/1077>`_
+- feat: adding containers to automatic launcher `#1090 <https://github.com/ansys/pyansys-geometry/pull/1090>`_
+- feat: minor changes to Linux Dockerfile `#1111 <https://github.com/ansys/pyansys-geometry/pull/1111>`_
+- feat: avoid error if folder exists `#1125 <https://github.com/ansys/pyansys-geometry/pull/1125>`_
+
+
+Changed
+^^^^^^^
+
+- build: changing sphinx-autoapi from 3.1.a2 to 3.1.a4 `#1038 <https://github.com/ansys/pyansys-geometry/pull/1038>`_
+- chore: add pre-commit.ci configuration `#1065 <https://github.com/ansys/pyansys-geometry/pull/1065>`_
+- chore: dependabot PR automatic approval `#1067 <https://github.com/ansys/pyansys-geometry/pull/1067>`_
+- ci: bump the actions group with 1 update `#1082 <https://github.com/ansys/pyansys-geometry/pull/1082>`_
+- chore: update docker tags to be kept `#1085 <https://github.com/ansys/pyansys-geometry/pull/1085>`_
+- chore: update pre-commit versions `#1094 <https://github.com/ansys/pyansys-geometry/pull/1094>`_
+- build: use ansys-sphinx-theme autoapi target `#1097 <https://github.com/ansys/pyansys-geometry/pull/1097>`_
+- fix: removing @PipKat from ``*.md`` files - changelog fragments `#1098 <https://github.com/ansys/pyansys-geometry/pull/1098>`_
+- ci: dashboard upload does not apply anymore `#1099 <https://github.com/ansys/pyansys-geometry/pull/1099>`_
+- chore: pre-commit.ci not working properly `#1108 <https://github.com/ansys/pyansys-geometry/pull/1108>`_
+- chore: update and adding pre-commit.ci config hook `#1109 <https://github.com/ansys/pyansys-geometry/pull/1109>`_
+- ci: main Python version update to 3.12 `#1112 <https://github.com/ansys/pyansys-geometry/pull/1112>`_
+- ci: skip Linux tests with common approach `#1113 <https://github.com/ansys/pyansys-geometry/pull/1113>`_
+- ci: build changelog on release `#1118 <https://github.com/ansys/pyansys-geometry/pull/1118>`_
+- chore: update CHANGELOG for v0.5.0 `#1119 <https://github.com/ansys/pyansys-geometry/pull/1119>`_
+
+Fixed
+^^^^^
+
+- feat: re-enable open file on Linux `#817 <https://github.com/ansys/pyansys-geometry/pull/817>`_
+- fix: adapt export and download tests to new hoops `#1057 <https://github.com/ansys/pyansys-geometry/pull/1057>`_
+- fix: linux Dockerfile - replace .NET6.0 references by .NET8.0 `#1069 <https://github.com/ansys/pyansys-geometry/pull/1069>`_
+- fix: misleading docstring for sweep_chain() `#1070 <https://github.com/ansys/pyansys-geometry/pull/1070>`_
+- fix: prepare_and_start_backend is only available on Windows `#1076 <https://github.com/ansys/pyansys-geometry/pull/1076>`_
+- fix: unit tests failing after dms update `#1087 <https://github.com/ansys/pyansys-geometry/pull/1087>`_
+- build: beartype upper limit on v0.18 `#1095 <https://github.com/ansys/pyansys-geometry/pull/1095>`_
+- fix: improper types being passed for Face and Edge ctor. `#1096 <https://github.com/ansys/pyansys-geometry/pull/1096>`_
+- fix: return type should be dict and not ``ScalarMapContainer`` (grpc type) `#1103 <https://github.com/ansys/pyansys-geometry/pull/1103>`_
+- fix: env version for Dockerfile Windows `#1120 <https://github.com/ansys/pyansys-geometry/pull/1120>`_
+- fix: changelog description ill-formatted `#1121 <https://github.com/ansys/pyansys-geometry/pull/1121>`_
+- fix: solve issues with intersphinx when releasing `#1123 <https://github.com/ansys/pyansys-geometry/pull/1123>`_
+
+Dependencies
+^^^^^^^^^^^^
+
+- build: bump the docs-deps group with 2 updates `#1062 <https://github.com/ansys/pyansys-geometry/pull/1062>`_, `#1093 <https://github.com/ansys/pyansys-geometry/pull/1093>`_, `#1105 <https://github.com/ansys/pyansys-geometry/pull/1105>`_
+- build: bump ansys-api-geometry from 0.3.13 to 0.4.0 `#1066 <https://github.com/ansys/pyansys-geometry/pull/1066>`_
+- build: bump the docs-deps group with 1 update `#1080 <https://github.com/ansys/pyansys-geometry/pull/1080>`_
+- build: bump pytest-cov from 4.1.0 to 5.0.0 `#1081 <https://github.com/ansys/pyansys-geometry/pull/1081>`_
+- build: bump ansys-api-geometry from 0.4.0 to 0.4.1 `#1092 <https://github.com/ansys/pyansys-geometry/pull/1092>`_
+- build: bump beartype from 0.17.2 to 0.18.2 `#1106 <https://github.com/ansys/pyansys-geometry/pull/1106>`_
+- build: bump ansys-tools-path from 0.4.1 to 0.5.1 `#1107 <https://github.com/ansys/pyansys-geometry/pull/1107>`_
+- build: bump panel from 1.4.0 to 1.4.1 in the docs-deps group `#1114 <https://github.com/ansys/pyansys-geometry/pull/1114>`_
+- build: bump scipy from 1.12.0 to 1.13.0 `#1115 <https://github.com/ansys/pyansys-geometry/pull/1115>`_
+
+
+Miscellaneous
+^^^^^^^^^^^^^
+
+- [pre-commit.ci] pre-commit autoupdate `#1063 <https://github.com/ansys/pyansys-geometry/pull/1063>`_
+- docs: add examples on new methods `#1089 <https://github.com/ansys/pyansys-geometry/pull/1089>`_
+- chore: pre-commit automatic update `#1116 <https://github.com/ansys/pyansys-geometry/pull/1116>`_
+
+.. vale on
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -301,17 +301,29 @@ def intersphinx_pyansys_geometry(switcher_version: str):
 latex_elements = {"preamble": latex.generate_preamble(html_title)}
 sd_fontawesome_latex = True
 
-linkcheck_exclude_documents = ["index", "getting_started/local/index", "assets"]
+linkcheck_exclude_documents = ["index", "getting_started/local/index"]
 linkcheck_ignore = [
-    r"https://github.com/ansys/pyansys-geometry-binaries/.*",
+    r"https://github.com/ansys/pyansys-geometry-binaries",
     r"https://download.ansys.com/",
     r".*/examples/.*.py",
     r".*/examples/.*.ipynb",
+    r"_static/assets/.*",
 ]
 
+# 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/ansys/pyansys-geometry/releases/download/v{__version__}/.*"
+    )  # noqa: E501
+    linkcheck_ignore.append(
+        f"https://github.com/ansys/pyansys-geometry/releases/tag/v{__version__}"
+    )  # noqa: E501
+
 # User agent
 user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 Edg/123.0.2420.81"  # noqa: E501
 
+
 # -- Declare the Jinja context -----------------------------------------------
 exclude_patterns = []
 BUILD_API = True if os.environ.get("BUILD_API", "true") == "true" else False

diff --git a/doc/source/getting_started/docker/windows_container.rst b/doc/source/getting_started/docker/windows_container.rst
@@ -112,9 +112,8 @@ There are two build modes:
   is being built.
 
 * **Build from available binaries**: This mode builds the Docker image using
-  the binaries available in the ``ansys/pyansys-geometry-binaries`` repository.
+  the binaries available in the `ansys/pyansys-geometry-binaries <https://github.com/ansys/pyansys-geometry-binaries>`_ repository.
   If you do not have access to this repository, you can only use the first mode.
-  Link to the binaries repository: https://github.com/ansys/pyansys-geometry-binaries/
 
 Prerequisites
 ~~~~~~~~~~~~~
@@ -159,7 +158,7 @@ Prior to building your image, follow these steps:
 * Download the `latest Windows Dockerfile <https://github.com/ansys/pyansys-geometry/blob/main/docker/windows/Dockerfile>`_.
 
 * Download the `latest release artifacts for the Windows
-  Docker container (ZIP file) for your version <https://github.com/ansys/pyansys-geometry-binaries/>`_.
+  Docker container (ZIP file) for your version <https://github.com/ansys/pyansys-geometry-binaries>`_.
 
 .. note::
 

diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -77,3 +77,4 @@ PyAnsys Geometry is a Python client library for the Ansys Geometry service.
        {% endif %}
        contributing
        assets
+       changelog
diff --git a/pyproject.toml b/pyproject.toml
@@ -131,12 +131,11 @@ testpaths = ["tests"]
 
 [tool.towncrier]
 directory = "doc/changelog.d"
-filename = "CHANGELOG.md"
-start_string = "<!-- towncrier release notes start -->\n"
-underlines = ["", "", ""]
+filename = "doc/source/changelog.rst"
 template = "doc/changelog.d/changelog_template.jinja"
-title_format = "## [{version}](https://github.com/ansys/pyansys-geometry/releases/tag/v{version}) - {project_date}"
-issue_format = "[#{issue}](https://github.com/ansys/pyansys-geometry/pull/{issue})"
+start_string = ".. towncrier release notes start\n"
+title_format = "`{version} <https://github.com/ansys/pyansys-geometry/releases/tag/v{version}>`_ - {project_date}"
+issue_format = "`#{issue} <https://github.com/ansys/pyansys-geometry/pull/{issue}>`_"
 
 [[tool.towncrier.type]]
 directory = "added"