docs: Improve documentation (#289)

Co-authored-by: pyansys-ci-bot <[email protected]>

Author: klmcadams

Diff for: README.rst

@@ -31,189 +31,14 @@ Ansys pre-commit hooks
    :alt: pre-commit.ci status
 
 This Ansys repository contains `pre-commit`_ hooks for different purposes.
-Currently, these hooks are available:
+The following hooks are currently available:
 
 * ``add-license-headers``: Add missing license headers to files by using
   `REUSE <https://reuse.software/>`_ . To use this hook, you must
   have ``REUSE`` implemented in your repository.
 * ``tech-review``: Do a technical review of your repository according to
   `Ansys repository requirements <https://dev.docs.pyansys.com/packaging/structure.html>`_
 
-``add-license-headers`` setup
------------------------------
-
-Add required directories
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you are using the ansys.jinja2 template and MIT.txt license, skip this step. By default, the hook will make symbolic links
-from its "assets" directory containing LICENSES/MIT.txt and .reuse/templates/ansys.jinja2
-to your repository when the hook runs. The .reuse and LICENSES directories will be deleted once the hook is
-done running.
-
-If you are using a custom template, create a directory named ``.reuse``, and if you are using a custom license, create a directory
-named ``LICENSES`` in the root of your repository. The custom template cannot be named ``ansys.jinja2``, otherwise it will be removed
-after the hook is done running. The custom license cannot be named ``MIT.txt`` for the same reason. The ``.reuse`` and/or ``LICENSES``
-directories will have to be committed to your repository and will not be removed once the hook is done running as long as there
-are custom templates or licenses in those directories. Your project should have the following layout:
-
- ::
-
-   project
-   ├── LICENCES
-   │   └── license_name.txt
-   ├── .reuse
-   │   └── templates
-   │       └── template_name.jinja2
-   ├── src
-   ├── examples
-   ├── tests
-   ├── .pre-commit-config.yaml
-   ├── pyproject.toml
-
-Where ``license_name`` is the name of the license that is being used, for example, MIT.txt, and
-``template_name`` is the name of the custom template being used. The jinja2 file contains the
-template for the license headers that are added to the files.
-
-Licenses that are supported by ``REUSE`` can be found in the
-`spdx/license-list-data <https://github.com/spdx/license-list-data/tree/main/text>`_ repository.
-Please select a license text file from that repository, and copy it to the LICENSES directory.
-
-Set custom arguments
-^^^^^^^^^^^^^^^^^^^^
-
-.. code:: yaml
-
-   - repo: https://github.com/ansys/pre-commit-hooks
-     rev: v0.5.1
-     hooks:
-     - id: add-license-headers
-       args: ["--custom_copyright", "custom copyright phrase", "--custom_template", "template_name", "--custom_license", "license_name", "--ignore_license_check", "--start_year", "2023"]
-
-``args`` can also be formatted as follows:
-
-.. code:: yaml
-
-   args:
-   - --custom_copyright=custom copyright phrase
-   - --custom_template=template_name
-   - --custom_license=license_name
-   - --ignore_license_check
-   - --start_year=2023
-
-* ``custom copyright phrase`` is the copyright line you want to include in the license
-  header. By default, it uses ``"ANSYS, Inc. and/or its affiliates."``.
-* ``template_name`` is the name of the .jinja2 file located in ``.reuse/templates/``.
-  By default, it uses ``ansys``.
-* ``license_name`` is the name of the license being used. For example, MIT, ECL-1.0, etc.
-  To view a list of licenses that are supported by ``REUSE``, see
-  https://github.com/spdx/license-list-data/tree/main/text. By default it uses ``MIT``.
-* ``ignore_license_check`` is whether or not to check for the license in the header. By default,
-  it is ``False``, meaning the files are checked for both the copyright and licensing information
-  in the header. Add ``--ignore_license_check`` to ignore checking for licensing information
-  in the files.
-* ``start_year`` is the start year of the copyright statement. By default, the ``start_year`` is
-  the current year, making the copyright statement
-  "Copyright (C) 2024 ANSYS, Inc. and/or its affiliates." If you are adding license headers
-  to packages released before the current year, add the ``start_year`` argument with the year your
-  package was released. For example, if ``start_year`` is 2023, the copyright statement would be
-  "Copyright (C) 2023 - 2024 ANSYS, Inc. and/or its affiliates." assuming the current year is 2024.
-
-Specify directories to run the hook on
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default, the hook will run on proto files in any directory, as well as python files within
-directories named ``src``, ``examples``, and ``tests``. To specify additional files and/or directories
-the hook should run on, add the necessary regex to the ``files`` line in your
-.pre-commit-config.yaml file:
-
-.. code:: yaml
-
-   - repo: https://github.com/ansys/pre-commit-hooks
-     rev: v0.5.1
-     hooks:
-     - id: add-license-headers
-       files: '(src|examples|tests|newFolder)/.*\.(py|newExtension)|\.(proto|newExtension)'
-
-Ignore specific files or file types
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In .pre-commit-config.yaml:
-
-.. code:: yaml
-
-  - repo: https://github.com/ansys/pre-commit-hooks
-    rev: v0.5.1
-    hooks:
-    - id: add-license-headers
-      exclude: |
-          (?x)^(
-              path/to/file1.py |
-              path/to/.*\.(ts|cpp) |
-              (.folder1|folder2)/.* |
-              .*\.js |
-              \..* |
-          )$
-
-* ``path/to/file1.py`` excludes the stated file.
-* ``path/to/.*\.(ts|cpp)`` excludes all .ts and .cpp files within the ``path/to`` directory.
-* ``(.folder1|folder2)/.*`` excludes directories named .folder1 and folder2.
-* ``.*\.js`` excludes all .js files in all directories.
-* ``\..*`` excludes all hidden files.
-
-``tech-review`` setup
----------------------
-
-These are the default values for the arguments of the tech-review hook:
-
-* ``--author_maint_name=ANSYS, Inc.``
-* ``[email protected]``
-* ``--license=MIT``
-* ``--url=https://github.com/ansys/{repo-name}``, replacing ``repo-name`` with the name of the repository
-
-The ``--author_maint_name`` is the name of the author and maintainer in the ``pyproject.toml`` file.
-By default, it is "Ansys, Inc.".
-
-The ``--author_maint_email`` is the email of the author and maintainer in the ``pyproject.toml`` file.
-By default, it is "[email protected]".
-
-The ``--license`` argument is the license that is being used by your repository. By default, it is
-MIT.
-
-The ``--url`` argument is automatically rendered based on the repository name. If your repository
-is not in the Ansys organization, please add this argument to your configuration in
-.pre-commit-config.yaml.
-
-The ``--product`` argument is required if a ``README.rst`` or ``README.md`` file does not
-exist in your repository and you want the template to render correctly. The product
-for ``PyMechanical`` would be ``mechanical``, for example.
-
-The ``--non_compliant_name`` flag can be used if your repository does not follow the typical
-naming convention of ``ansys-*-*``.
-
-Technical review hook in ``ansys/pre-commit-hooks``' .pre-commit-config.yaml file:
-
-.. code:: yaml
-
-  - repo: https://github.com/ansys/pre-commit-hooks
-    rev: v0.5.1
-    hooks:
-    - id: tech-review
-      args:
-      - --product=pre_commit_hooks
-      - --non_compliant_name
-
-Technical review hook in ``PyMechanical``'s .pre-commit-config.yaml file:
-
-.. code:: yaml
-
-  - repo: https://github.com/ansys/pre-commit-hooks
-    rev: v0.5.1
-    hooks:
-    - id: tech-review
-      args:
-      - --product=mechanical
-
-
 How to install
 --------------
 

Diff for: doc/changelog.d/289.documentation.md

@@ -0,0 +1 @@
+Improve documentation

Diff for: doc/source/_static/images/license-header-dark.PNG

@@ -0,0 +1,75 @@
+.. title:: Creating pre-commit hooks
+
+Creating a pre-commit hook
+==========================
+
+1. Create a Python file in the `src/ansys/pre_commit_hooks <https://github.com/ansys/pre-commit-hooks/tree/main/src/ansys/pre_commit_hooks>`_
+   directory. For example, ``new_hook.py``, with a main function:
+
+   .. code:: python
+
+      def main():
+          print("New hook!")
+          return 0
+
+      if __name__ == "__main__":
+          main()
+
+   .. note::
+
+      The ``main`` function of the hook must return a non-zero exit code if the hook fails. For the
+      hooks in the Ansys Pre-Commit Hooks repository, the exit code is set to 1 if the hook fails
+      and 0 if the hook passes.
+
+2. Create a Python file to test the hook in the `tests <https://github.com/ansys/pre-commit-hooks/tree/main/tests>`_
+   directory. For example, ``test_new_hook.py``.
+
+3. Add the hook to the ``.pre-commit-hooks.yaml`` file:
+
+   .. code:: yaml
+
+      - id: "new-hook"
+        name: "New Hook"
+        description: "A new pre-commit hook for the Ansys Pre-Commit Hooks repository"
+        entry: new-hook
+        language: python
+
+   In the ``.pre-commit-hooks.yaml`` file, you can include additional information about the hook
+   in the ``files``, ``requires-serial``, or ``pass_filenames`` fields. For more information, see
+   the `Creating new hooks <https://pre-commit.com/#creating-new-hooks>`_ page in the
+   ``pre-commit`` documentation.
+
+4. Add the hook to the ``entry_points`` dictionary in the ``setup.py`` file:
+
+   .. code:: python
+
+      entry_points = {
+          "console_scripts": [
+              "new-hook = ansys.pre_commit_hooks.new_hook:main",
+          ],
+      },
+
+5. After adding code to the pre-commit hook file, for example, ``new_hook.py``, add the hook's
+   required dependencies to the ``pyproject.toml`` and ``setup.py`` files if they are not already
+   there:
+
+   In the ``pyproject.toml`` file, add the dependency in the ``requires`` list under the
+   ``[build-system]`` section, pinning the dependency to a specific version:
+
+   .. code:: toml
+
+      [build-system]
+      requires = [
+          "setuptools>=42.0",
+          "GitPython==3.1.44",
+      ]
+
+   In the ``setup.py`` file, add the dependency to the ``install_requires`` list, pinning
+   the dependency to a specific version:
+
+   .. code:: python
+
+       install_requires = [
+           "GitPython==3.1.44",
+           "importlib-metadata==8.6.1",
+       ]

Diff for: doc/source/_static/images/license-header-light.png

@@ -0,0 +1,33 @@
+.. title:: Contribute
+
+Contribute
+==========
+
+Learn how to contribute to the Ansys Pre-Commit Hooks repository.
+
+.. grid:: 3
+
+    .. grid-item-card:: Create a pre-commit hook :octicon:`code-square`
+        :padding: 2 2 2 2
+        :link: add-hook
+        :link-type: doc
+
+        How to add a pre-commit hook to the repository
+
+        :bdg-primary-line:`Create new hook`
+
+    .. grid-item-card:: Test a pre-commit hook :octicon:`note`
+        :padding: 2 2 2 2
+        :link: testing
+        :link-type: doc
+
+        How to test a pre-commit hook locally
+
+        :bdg-primary-line:`Test`
+
+.. toctree::
+   :hidden:
+   :maxdepth: 3
+
+   add-hook
+   testing

Diff for: doc/source/contribute/add-hook.rst

@@ -0,0 +1,69 @@
+.. title:: Testing pre-commit hooks
+
+Testing a pre-commit hook
+=========================
+
+Running ``pre-commit`` locally
+------------------------------
+
+To ensure a pre-commit hook works as expected, run ``pre-commit`` locally on the repository. First,
+install the ``ansys/pre-commit-hooks`` project in a virtual environment:
+
+.. tab-set::
+
+  .. tab-item:: Linux
+
+     .. code:: bash
+
+        python -m venv .venv
+        source .venv/bin/activate
+        pip install -e .
+
+  .. tab-item:: Windows
+
+     .. code:: batch
+
+        python -m venv .venv
+        .venv\Scripts\activate
+        pip install -e .
+
+Next, add the pre-commit hook to the repository's ``.pre-commit-config.yaml`` file, copying the
+details of the hook from the ``.pre-commit-hooks.yaml`` file. For example, to add the ``new-hook``
+hook:
+
+.. code:: yaml
+
+   - repo: local
+     hooks:
+     - id: "new-hook"
+       name: "New Hook"
+       description: "A new pre-commit hook for the Ansys Pre-Commit Hooks repository"
+       entry: new-hook
+       language: python
+
+Run ``pre-commit`` on the repository:
+
+.. code:: bash
+
+   pre-commit run --all-files --verbose
+
+Make sure to test the hook locally on both Linux and Windows operating systems.
+
+Running ``pytest`` tests
+------------------------
+
+Create tests using ``pytest`` in the ``tests`` directory to ensure functions in the hook work as
+expected. For example, in ``test_new_hook.py``:
+
+.. code:: python
+
+    import pytest
+    import ansys.pre_commit_hooks.new_hook as hook
+
+    def test_main():
+        """Test the main function of the new-hook."""
+        # Assert main passes
+        assert hook.main() == 0
+
+For more information on writing tests, see the
+`pytest documentation <https://docs.pytest.org/en/stable/>`_.