docs: restructure duplicated content (#752)

* docs: rename sessions

* fix: coding style

* docs: add cicd reusable actions

* docs: add cicd reusable actions

* fix: vale

* fix: formatting tools

* docs: remove docstyle

* docs: update the index

* docs: update the index

* docs: update the index

* Apply suggestions from code review

Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com>

* docs: update the links

* ci: update the labeler

* ci: labels

* ci: test ubundu latest

* ci: revert

* Apply suggestion from @Revathyvenugopal162

---------

Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com>

Author: Revathyvenugopal162

.github/labeler.yml

@@ -1,9 +1,25 @@
+# -- Labels based on PR title ------------------------------------------------
+
+'fix':
+  - head-branch: ['fix']
+
+'enhancement':
+  - head-branch: ['feat']
+ 
+
 documentation:
-- changed-files:
-  - any-glob-to-any-file: ['doc/source/**/*']
+- any:
+  - changed-files:
+    - any-glob-to-any-file: ['doc/source/**/*']
+  - head-branch: ['docs', 'doc']
+
 maintenance:
-- changed-files:
-  - any-glob-to-any-file: ['.github/**/*', 'ruff.toml', 'pyproject.toml', 'docker/**/*']
+- any: 
+  - changed-files:
+    - any-glob-to-any-file: ['.github/**/*', 'ruff.toml', '.pre-commit-config.yaml']
+  - head-branch: ['maint', 'ci', 'no-ci']
+
 dependencies:
-- changed-files:
-  - any-glob-to-any-file: ['requirements/*']
+- any:
+  - changed-files:
+    - any-glob-to-any-file: ['requirements/*']

.github/labels.yml

@@ -1,35 +1,32 @@
-- name: bug
+- name: 'bug'
   description: Something isn't working
   color: d42a34
 
-- name: dependencies
+- name: 'dependencies'
   description: Related with project dependencies
   color: FFD827
 
-- name: documentation
+- name: 'documentation'
   description: Improvements or additions to documentation
   color: 0677ba
 
-- name: enhancement
+- name: 'enhancement'
   description: New features or code improvements
   color: ffc0cb
 
-- name: good first issue
+- name: 'good first issue'
   description: Easy to solve for newcomers
   color: 62ca50
 
-- name: maintenance
+- name: 'maintenance'
   description: Package and maintenance related
   color: f78c37
 
-- name: graphics
+- name: 'graphics'
   description: Related with plotting utilities
   color: 000000
 
-- name: support
+- name: 'support'
   description: Further information is requested
   color: 6a32a5
 
-- name: release
-  description: Checklist for an upcoming release
-  color: ffffff

.github/workflows/labeler.yml

@@ -33,31 +33,3 @@ jobs:
       with:
         repo-token: "${{ secrets.GITHUB_TOKEN }}"
 
-    # Label based on branch name
-    - uses: actions-ecosystem/action-add-labels@18f1af5e3544586314bbe15c0273249c770b2daf # v1.1.3
-      if: |
-        startsWith(github.event.pull_request.head.ref, 'doc') || 
-        startsWith(github.event.pull_request.head.ref, 'docs')
-      with:
-        labels: documentation
-
-    - uses: actions-ecosystem/action-add-labels@18f1af5e3544586314bbe15c0273249c770b2daf # v1.1.3
-      if: |
-        startsWith(github.event.pull_request.head.ref, 'maint') ||
-        startsWith(github.event.pull_request.head.ref, 'no-ci') ||
-        startsWith(github.event.pull_request.head.ref, 'docker') ||
-        startsWith(github.event.pull_request.head.ref, 'ci')
-      with:
-        labels: maintenance
-
-    - uses: actions-ecosystem/action-add-labels@18f1af5e3544586314bbe15c0273249c770b2daf # v1.1.3
-      if: startsWith(github.event.pull_request.head.ref, 'feat')
-      with:
-        labels: |
-          enhancement
-    - uses: actions-ecosystem/action-add-labels@18f1af5e3544586314bbe15c0273249c770b2daf # v1.1.3
-      if: |
-        startsWith(github.event.pull_request.head.ref, 'fix') ||
-        startsWith(github.event.pull_request.head.ref, 'patch')
-      with:
-        labels: bug

README.rst

@@ -15,8 +15,3 @@ This guide describes the PyAnsys project organization and administration.
 It also provides how-to information and summarizes packaging, coding, and
 documentation styles. It concludes with an abstractions section that explains
 how apps and complex services expose only functionalities that matter to users.
-
-From the **About** area for the repository, you can click the link to view
-the latest web-based release of this guide. In the `Releases <https://github.com/ansys/pyansys-dev-guide/releases>`_
-area, you can view information about all releases. In the **Assets**  area for
-any release, you can download a PDF file of the guide.

doc/source/coding-style/deprecation.rst

@@ -7,6 +7,11 @@ there is no official guidance on deprecating features within Python.
 Thus, this topic provides deprecation best practices for PyAnsys
 libraries. 
 
+.. note::
+    This page covers API-level deprecation of methods, classes, and functions.
+    For retiring an entire repository or package lifecycle, see
+    :ref:`deprecating`.
+
 Whenever you deprecate a method, class, or function, you must take one of
 these actions:
 

doc/source/coding-style/formatting-tools.rst

@@ -7,20 +7,26 @@ There are many tools for checking code style. This section presents some of
 the most popular ones in the Python ecosystem. A minimum configuration is
 provided for each one so that you can easily include them in your PyAnsys project.
 
+.. note::
+    This page focuses on code-quality automation for Python projects.
+    For documentation-focused tools such as ``blacken-docs``, ``docformatter``,
+    ``Vale``, and ``numpydoc`` validation, see
+    :ref:`doc_style_tools`.
+
 Most of the tools presented can be configured using :ref:`the
 \`\`pyproject.toml\`\` file`. Avoiding dotfiles leads to a much
 cleaner root project directory.
 
 Ruff
 ----
 
-`Ruff`_ is a Python linter and code formatter written in Rust. It aims to be 
-orders of magnitude faster than alternative tools while integrating more 
-functionality behind a single, common interface. Ruff can therefore be used 
-to replace the previously preferred alternatives that were `Flake8`_ 
+`Ruff`_ is a Python linter and code formatter written in Rust. It aims to be
+orders of magnitude faster than alternative tools while integrating more
+functionality behind a single, common interface. Ruff can therefore be used
+to replace the previously preferred alternatives that were `Flake8`_
 (natively re-implementing its popular plugins), `Black`_ and `isort`_.
 
-It is actively developed, used in major open-source projects, and offers the following 
+It is actively developed, used in major open-source projects, and offers the following
 features and advantages:
 
 - Can be installed via ``pip install ruff``
@@ -47,6 +53,7 @@ may look like this:
     [tool.ruff.format]
     quote-style = "double"
     indent-style = "space"
+    docstring-code-format = true
 
     [tool.ruff.lint]
     select = [
@@ -57,6 +64,7 @@ may look like this:
         "N",    # pep8-naming, see https://docs.astral.sh/ruff/rules/#pep8-naming-n
         "PTH",  # flake8-use-pathlib, https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
         "TD",   # flake8-todos, https://docs.astral.sh/ruff/rules/#flake8-todos-td
+        "W",    # pycodestyle, see https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
     ]
     ignore = [
         "TD003", # Missing issue link in TODOs comment
@@ -69,9 +77,9 @@ may look like this:
     combine-as-imports = true
     force-sort-within-sections = true
 
-Linting and formatting rules shall be added step by step when migrating a project to Ruff, 
-gradually resolving the triggered errors. For more information about configuring Ruff, as 
-well as a complete description of the available rules and settings, please refer to the 
+Linting and formatting rules shall be added step by step when migrating a project to Ruff,
+gradually resolving the triggered errors. For more information about configuring Ruff, as
+well as a complete description of the available rules and settings, see the
 `tool's documentation <https://docs.astral.sh/ruff/configuration/>`__.
 
 
@@ -126,13 +134,13 @@ configuration that includes both code and documentation formatting tools.
 .. code-block:: yaml
 
     repos:
-    
+
     - repo: https://github.com/astral-sh/ruff-pre-commit
       rev: vX.Y.Z
       hooks:
       - id: ruff
       - id: ruff-format
-    
+
     - repo: https://github.com/codespell-project/codespell
       rev: vX.Y.Z
       hooks:
@@ -144,7 +152,7 @@ configuration that includes both code and documentation formatting tools.
       - id: pydocstyle
         additional_dependencies: [toml]
         exclude: "tests/"
-
+    
     - repo: https://github.com/ansys/pre-commit-hooks
       rev: v0.2.4
       hooks:
@@ -168,7 +176,7 @@ Then, ensure that you install it as a ``Git hook`` by running this command:
 Use ``pre-commit``
 ~~~~~~~~~~~~~~~~~~
 
-One installed as described, ``pre-commit`` automatically triggers every time
+Once installed as described, ``pre-commit`` automatically triggers every time
 that you try to commit a change. If any hook defined in the ``.pre-commit-config.yaml``
 file fails, you must fix the failing files, stage the new changes, and try to commit
 them again.
@@ -280,3 +288,40 @@ Use the following configuration in your ``.pre-commit-config.yaml`` file to be c
 
     repos:
         # Your repository-specific configurations here
+
+CI/CD integration with Ansys reusable actions
+----------------------------------------------
+
+The PyAnsys ecosystem provides a set of reusable GitHub Actions in the
+`ansys/actions <https://actions.docs.ansys.com/version/stable/index.html>`_
+repository. These actions encapsulate common CI/CD tasks so that individual
+PyAnsys projects do not need to re-implement them from scratch.
+
+For code style enforcement in CI, use the ``code-style`` action. It internally
+runs ``pre-commit`` with all hooks defined in your ``.pre-commit-config.yaml``
+file, guaranteeing that every pull request is checked against the same rules
+that developers run locally.
+
+A minimal job definition looks like this:
+
+.. code-block:: yaml
+
+    code-style:
+      name: "Code style"
+      runs-on: ubuntu-latest
+      steps:
+        - name: "Code style"
+          uses: ansys/actions/code-style@vX.Y.Z
+          with:
+            python-version: ${{ env.MAIN_PYTHON_VERSION }}
+
+.. note::
+
+    Replace ``vX.Y.Z`` with the latest available version. For the full list of
+    inputs and outputs supported by this action, see the
+    `Code style action documentation
+    <https://actions.docs.ansys.com/version/stable/style-actions/index.html#code-style-action>`_.
+
+For a complete list of all reusable actions provided by the PyAnsys ecosystem,
+see the `Ansys actions documentation
+<https://actions.docs.ansys.com/version/stable/index.html>`_.

doc/source/coding-style/index.rst

@@ -35,5 +35,4 @@ within Python.
 
    pep8
    formatting-tools
-   required-standard
    deprecation

doc/source/coding-style/required-standard.rst

@@ -52,6 +52,7 @@
         "min_chars_for_search": 2,
         "ignoreLocation": True,
     },
+    "header_links_before_dropdown": 6,
 }
 
 # necessary for proper breadcrumb title