feat: add whatsnew options (#583)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Jorge Martínez <[email protected]>
Co-authored-by: klmcadams <[email protected]>
Co-authored-by: Kerry McAdams <[email protected]>
Co-authored-by: Roberto Pastor Muela <[email protected]>

Author: 5 people

.gitattributes

@@ -0,0 +1,3 @@
+* text=auto !eol
+*.sh         eol=lf
+*.bat        eol=crlf

.github/workflows/ci_cd.yml

@@ -45,6 +45,19 @@ jobs:
       pull-requests: write
     runs-on: ubuntu-latest
     steps:
+      - name: "Setup python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.MAIN_PYTHON_VERSION }}
+
+      - name: "Checkout repo"
+        uses: actions/checkout@v4
+
+      - name: "Install dependencies"
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[changelog]
+
       - uses: ansys/actions/doc-changelog@v8
         if: ${{ github.event_name == 'pull_request' }}
         with:

.pre-commit-config.yaml

@@ -34,7 +34,7 @@ repos:
     - id: check-github-workflows
 
 - repo: https://github.com/ansys/pre-commit-hooks
-  rev: v0.4.4
+  rev: v0.5.1
   hooks:
   - id: add-license-headers
     files: '(src|doc/source/examples)/.*\.(py)'

doc/changelog.d/583.documentation.md

@@ -0,0 +1 @@
+feat: add whatsnew options

doc/changelog.d/changelog_template.jinja

@@ -1,17 +1,17 @@
-{% 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 %}
+{% 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 %}

doc/source/_static/whatsnew_section.png

@@ -1,10 +1,9 @@
+
 .. _ref_release_notes:
 
 Release notes
 #############
 
-This document contains the release notes for the project.
-
 .. vale off
 
 .. towncrier release notes start

doc/source/_static/whatsnew_sidebar.png

@@ -256,3 +256,91 @@ main ``index.rst`` file and the ``learning.rst`` file in its "Getting started" s
     To use this feature, you must have the `quarto <https://quarto.org/>` package installed. To create thumbnails of generated PDF files,
     the theme is using `pdf2image`. So you should have the ``poppler`` package installed in your system.
     For more information, see the `pdf2image documentation <https://pypi.org/project/pdf2image/>`_.
+
+What's new section
+------------------
+
+The "What's new" section is an option that allows you to highlight new features in your library
+for each minor version within the changelog file.
+
+To get started, create a YAML file named ``whatsnew.yml`` in the ``doc/source`` directory. The
+YAML file should contain the following structure:
+
+.. code-block:: yaml
+
+    fragments:
+    - title: Feature title
+      version: 0.2.0  # The version the feature is introduced
+      content: |
+        Feature description in RST format.
+
+    - title: Another feature title
+      version: 0.1.2
+      content: |
+        Feature description in RST format.
+
+The dropdown generation only supports the following RST formats in the "content" field:
+
+- Bold: Use double asterisks to wrap the text.
+- Italics: Use single asterisks to wrap the text.
+- Code samples: Use single or double backticks to wrap the text.
+- Links: Use the following format to include links:
+
+  .. code-block:: rst
+
+     `link text <https://www.example.com>`_
+
+- Code blocks: Use the following format to include code blocks:
+
+  .. code-block:: rst
+
+        .. code:: python
+
+           print("hello world")
+
+If a format is used in the "content" field that does not fall into the categories above, it will not
+be rendered correctly.
+
+To enable the "What's new" sections and sidebar in the changelog file, add the following dictionary
+to the ``html_theme_options`` dictionary:
+
+.. code-block:: python
+
+    html_theme_options = (
+        {
+            "whatsnew": {
+                "whatsnew_file_path": "changelog.d/whatsnew.yml",
+                "changelog_file_path": "changelog.rst",
+                "sidebar_pages": ["changelog"],
+                "sidebar_no_of_headers": 3,  # Optional
+                "sidebar_no_of_contents": 3,  # Optional
+            },
+        },
+    )
+
+The dictionary contains the following keys:
+
+- ``whatsnew_file_path``: The path to the YAML file containing what's new content local to the
+  ``doc/source`` directory. If not provided, the what's new section will not be generated.
+- ``changelog_file_path``: The path to the changelog.rst file local to the ``doc/source``
+  directory. If not provided, the what's new section will not be generated.
+- ``sidebar_pages``: List of names for the pages to include the what's new sidebar on. If not
+  provided, the what's new sidebar is not displayed.
+- ``sidebar_no_of_headers``: Number of minor version sections to display in the what's new sidebar.
+   By default, it displays three version sections in the sidebar.
+- ``sidebar_no_of_contents``: Number of what's new content to display under each minor version in the
+   what's new sidebar. If not provided, it displays all dropdowns by default.
+
+The following images show a sample "What's new" section and sidebar in the changelog file:
+
+.. tab-set::
+
+    .. tab-item:: What's new section
+
+        .. image:: ../_static/whatsnew_section.png
+           :alt: What's new section
+
+    .. tab-item:: What's new sidebar
+
+        .. image:: ../_static/whatsnew_sidebar.png
+           :alt: What's new sidebar

doc/source/changelog.rst

@@ -46,6 +46,7 @@ doc = [
     "Pillow>=9.0",
     "PyGitHub==2.5.0",
     "pyvista[jupyter]==0.44.2",
+    "PyYAML==6.0.2",
     "requests==2.32.3",
     "Sphinx==8.1.3",
     "sphinx-autoapi==3.4.0",
@@ -55,6 +56,10 @@ doc = [
     "sphinx-jinja==2.0.2",
     "sphinx-notfound-page==1.1.0",
 ]
+changelog = [
+    "PyYAML==6.0.2",
+    "sphinx-design==0.6.1",
+]
 
 [project.entry-points."sphinx.html_themes"]
 ansys_sphinx_theme = "ansys_sphinx_theme"
@@ -122,7 +127,7 @@ directory = "doc/changelog.d"
 filename = "doc/source/changelog.rst"
 template = "doc/changelog.d/changelog_template.jinja"
 start_string = ".. towncrier release notes start\n"
-title_format = "`{version} <https://github.com/ansys/ansys-sphinx-theme/releases/tag/v{version}>`_ - {project_date}"
+title_format = "`{version} <https://github.com/ansys/ansys-sphinx-theme/releases/tag/v{version}>`_ ({project_date})"
 issue_format = "`#{issue} <https://github.com/ansys/ansys-sphinx-theme/pull/{issue}>`_"
 
 [[tool.towncrier.type]]