Edits to RST and PY files (#28)

Co-authored-by: Roberto Pastor Muela <[email protected]>

Author: PipKat

README.rst

@@ -27,30 +27,31 @@ Ansys pre-commit hooks
    :alt: Black
 
 
-A repository containing a collection of `pre-commit`_ hooks for different purposes.
+This Ansys repository contains `pre-commit`_ hooks for different purposes.
+Currently, these hooks are available:
 
-The available hooks are the following:
-
-* ``add-license-headers``: Add missing license headers to files by using reuse lint and annotate.
-  Requires repositories to have `REUSE <https://reuse.software/>`_ implemented.
+* ``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.
 
 
 How to install
 --------------
 
-At least two installation modes are provided: user and developer.
+The following sections provide instructions for installing the ``ansys-pre-commit-hooks``
+package in two installation modes: user and developer.
 
 For users
 ^^^^^^^^^
 
-In order to install ansys-pre-commit-hooks library, make sure you
-have the latest version of `pip`_. To do so, run:
+Before installing the package, to ensure that you
+have the latest version of `pip`_, run this command:
 
 .. code:: bash
 
     python -m pip install -U pip
 
-Then, you can simply execute:
+Then, to install the package, run this command:
 
 .. code:: bash
 
@@ -59,19 +60,21 @@ Then, you can simply execute:
 For developers
 ^^^^^^^^^^^^^^
 
-Installing ansys-pre-commit-hooks library in developer mode allows
-you to modify the source and enhance it.
+Installing the package in developer mode allows you to modify and
+enhance the source code.
+
+Before contributing to the project, ensure that you are familiar with
+the `PyAnsys Developer's Guide`_.
 
-Before contributing to the project, please refer to the `PyAnsys Developer's guide`_. You will
-need to follow these steps:
+For a developer installation, you must follow these steps:
 
-#. Start by cloning this repository:
+#. Clone the repository with this command:
 
    .. code:: bash
 
       git clone https://github.com/ansys/pre-commit-hooks
 
-#. Create a fresh-clean Python environment and activate it:
+#. Create a fresh-clean Python environment and activate it with these commands:
 
    .. code:: bash
 
@@ -87,14 +90,15 @@ need to follow these steps:
       # Activate it in Windows Powershell
       .venv\Scripts\Activate.ps1
 
-#. Make sure you have the latest required build system tools:
+#. Ensure that you have the latest required build system tools by
+   running this command:
 
    .. code:: bash
 
       python -m pip install -U pip flit tox twine
 
 
-#. Install the project in editable mode:
+#. Install the project in editable mode by running one of these commands:
 
    .. code:: bash
 
@@ -110,7 +114,7 @@ need to follow these steps:
       # Install all requirements
       python -m pip install -e .[tests,doc]
 
-#. Finally, verify your development installation by running:
+#. Verify your development installation by running this command:
 
    .. code:: bash
 
@@ -120,37 +124,40 @@ need to follow these steps:
 How to test it
 --------------
 
-This project takes advantage of `tox`_. This tool allows to automate common
-development tasks (similar to Makefile) but it is oriented towards Python
-development.
+This project takes advantage of `tox`_. This tool automates common
+development tasks (similar to Makefile), but it is oriented towards
+Python development.
 
-Using tox
-^^^^^^^^^
+Using ``tox``
+^^^^^^^^^^^^^
+
+While Makefile has rules, ``tox`` has environments. In fact, ``tox`` creates its
+own virtual environment so that anything being tested is isolated from the project
+to guarantee the project's integrity.
 
-As Makefile has rules, `tox`_ has environments. In fact, the tool creates its
-own virtual environment so anything being tested is isolated from the project in
-order to guarantee project's integrity. The following environments commands are provided:
+These environment commands are provided:
 
-- **tox -e style**: will check for coding style quality.
-- **tox -e py**: checks for unit tests.
-- **tox -e py-coverage**: checks for unit testing and code coverage.
-- **tox -e doc**: checs for documentation building process.
+- **tox -e style**: Checks for coding style quality.
+- **tox -e py**: Checks for unit tests.
+- **tox -e py-coverage**: Checks for unit testing and code coverage.
+- **tox -e doc**: Checks for successfully building the documentation.
 
 
 Raw testing
 ^^^^^^^^^^^
 
-If required, you can always call the style commands (`black`_, `isort`_,
-`flake8`_...) or unit testing ones (`pytest`_) from the command line. However,
-this does not guarantee that your project is being tested in an isolated
-environment, which is the reason why tools like `tox`_ exist.
+If required, you can always call style commands, such as `black`_, `isort`_,
+and `flake8`_, or unit testing commands, such as `pytest`_, from the command line.
+However, calling these commands does not guarantee that your project is
+being tested in an isolated environment, which is the reason why tools like
+``tox`` exist.
 
 
 A note on ``pre-commit``
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 The style checks take advantage of `pre-commit`_. Developers are not forced but
-encouraged to install this tool via:
+encouraged to install this tool by running this command:
 
 .. code:: bash
 
@@ -160,14 +167,15 @@ encouraged to install this tool via:
 Documentation
 -------------
 
-For building documentation, you can either run the usual rules provided in the
-`Sphinx`_ Makefile, such us:
+For building documentation, you can run the usual rules provided in the
+`Sphinx`_ Makefile with a command that is formatted like this:
 
 .. code:: bash
 
     make -C doc/ html && your_browser_name doc/html/index.html
 
-However, the recommended way of checking documentation integrity is using:
+However, the recommended way of checking documentation integrity is by
+running ``tox`` with a command that is formatted like this:
 
 .. code:: bash
 
@@ -177,8 +185,8 @@ However, the recommended way of checking documentation integrity is using:
 Distributing
 ------------
 
-If you would like to create either source or wheel files, start by installing
-the building requirements and then executing the build module:
+If you would like to create either source or wheel files, install
+the building requirements and then execute the build module with these commands:
 
 .. code:: bash
 
@@ -193,7 +201,7 @@ the building requirements and then executing the build module:
 .. _isort: https://github.com/PyCQA/isort
 .. _pip: https://pypi.org/project/pip/
 .. _pre-commit: https://pre-commit.com/
-.. _PyAnsys Developer's guide: https://dev.docs.pyansys.com/
+.. _PyAnsys Developer's Guide: https://dev.docs.pyansys.com/
 .. _pytest: https://docs.pytest.org/en/stable/
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
 .. _tox: https://tox.wiki/

doc/source/_autoapi_templates/index.rst

@@ -1,7 +1,7 @@
 API reference
 =============
 
-This page contains the ``ansys-pre-commit-hooks`` API reference.
+This section provides descriptions of all API members for Ansys pre-commit hooks.
 
 .. toctree::
    :titlesonly:

src/ansys/pre_commit_hooks/__init__.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-"""Initialize package level imports."""
+"""Module for initializing package-level imports for Ansys pre-commit hooks."""
 
 try:
     import importlib.metadata as importlib_metadata

src/ansys/pre_commit_hooks/add_license_headers.py

@@ -21,7 +21,11 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-"""Run reuse for files missing license headers."""
+"""
+Module for running `REUSE <https://reuse.software/>`_ to add missing license headers to files.
+
+A license header consists of the Ansys copyright statement and licensing information.
+"""
 import argparse
 from datetime import date as dt
 import json
@@ -34,17 +38,17 @@
 
 def set_lint_args(parser):
     """
-    Add arguments to parser for reuse lint.
+    Add lint arguments to the parser for `REUSE <https://reuse.software/>`_.
 
     Parameters
     ----------
     parser: argparse.ArgumentParser
-        Parser without any arguments.
+        Parser without any lint arguments.
 
     Returns
     -------
     argparse.Namespace
-        Parser Namespace containing lint arguments.
+        Parser namespace containing lint arguments.
     """
     parser.add_argument("--loc", type=str, help="Path to repository location", default="src")
     parser.add_argument("--parser")
@@ -56,19 +60,19 @@ def set_lint_args(parser):
 
 def list_noncompliant_files(args, proj):
     """
-    Retrieve list of noncompliant files.
+    Get a list of the files that are missing license headers.
 
     Parameters
     ----------
     args: argparse.Namespace
         Namespace of arguments with their values.
     proj: project.Project
-        Project reuse runs on.
+        Project to run `REUSE <https://reuse.software/>`_ on.
 
     Returns
     -------
     list
-        List of files without license headers.
+        List of the files that are missing license headers.
     """
     # Create a temporary file containing lint.run json output
     filename = None
@@ -77,7 +81,8 @@ def list_noncompliant_files(args, proj):
         lint.run(args, proj, tmp)
         filename = tmp.name
 
-    # Open the temporary file, load the json, and find files missing copyright & licensing info.
+    # Open the temporary file, load the JSON file, and find files that
+    # are missing license headers.
     lint_json = None
     with open(filename, "rb") as file:
         lint_json = json.load(file)
@@ -95,16 +100,18 @@ def list_noncompliant_files(args, proj):
 
 def find_files_missing_header():
     """
-    Retrieve files without license header.
+    Find files that are missing license headers and run `REUSE <https://reuse.software/>`_ on them.
 
     Returns
     -------
     int
-        Returns non-zero int if one or more files are noncompliant,
-        or if the .reuse directory is missing.
+        ``1`` if ``REUSE`` changed all noncompliant files.
+
+        ``2`` if the ``.reuse`` directory does not exist in the root path of the
+        GitHub repository.
     """
     # Set up argparse for location, parser, and lint
-    # Lint contains 4 args: quiet, json, plain, and no_multiprocessing
+    # Lint contains four arguments: quiet, json, plain, and no_multiprocessing
     parser = argparse.ArgumentParser()
     args = set_lint_args(parser)
     proj = project.Project(rf"{args.loc}")
@@ -114,62 +121,66 @@ def find_files_missing_header():
     # Get current year for license file
     year = dt.today().year
 
-    # If there are files missing headers, run reuse and return 1
+    # If there are files missing headers, run REUSE and return 1
     if missing_headers:
-        # Returns 1 if reuse changes all noncompliant files
-        # Returns 2 if .reuse directory does not exist
+        # Returns 1 if REUSE changes all noncompliant files
+        # Returns 2 if .reuse directory does not exist in root of git repository
         return run_reuse(parser, year, args.loc, missing_headers)
 
     return 0
 
 
 def check_reuse_dir():
     """
-    Check .reuse directory exists in root of git repository.
+    Check if the ``.reuse`` directory exists in the root path of the git repository.
 
     Returns
     -------
     str
-        Root path of git repository.
+        Root path of the git repository.
     int
-        If .reuse directory does not exist at root path of git repository.
+        ``1`` if  the ``.reuse`` directory does not exist in the root path
+        of the git repository.
     """
     # Get root directory of current git repository
     git_repo = git.Repo(os.getcwd(), search_parent_directories=True)
     git_root = git_repo.git.rev_parse("--show-toplevel")
 
-    # If .reuse folder does not exist in git repository root, return 1
+    # If .reuse folder does not exist in root of git repository, return 1
     if not os.path.isdir(os.path.join(git_root, ".reuse")):
-        print(f"Please ensure the .reuse directory is in {git_root}")
+        print(f"Ensure that the .reuse directory is in {git_root}.")
         return 1
 
     return git_root
 
 
 def run_reuse(parser, year, loc, missing_headers):
     """
-    Run reuse command on files without license headers.
+    Run `REUSE <https://reuse.software/>`_ on files that are missing license headers.
 
     Parameters
     ----------
     parser: argparse.ArgumentParser
-        Parser containing previously set arguments.
+        Parser containing the previously set arguments.
     year: int
-        Current year for license header.
+        Current year for the license header.
     loc: str
-        Location to search for files missing headers.
+        Location to search for files that are missing license headers.
     missing_headers: list
-        List of files that are missing headers.
+        List of files that are missing license headers.
 
     Returns
     -------
     int
-        Fails pre-commit hook on return 1
+        ``1`` if the pre-commit hook fails.
+
+        ``2`` if  the ``.reuse`` directory does not exist in the root path
+        of the GitHub repository.
     """
-    # Add header arguments to parser which include: copyright, license, contributor, year,
-    # style, copyright-style, template, exclude-year, merge-copyrights, single-line,
+    # Add header arguments to parser. Arguments are: copyright, license, contributor,
+    # year, style, copyright-style, template, exclude-year, merge-copyrights, single-line,
     # multi-line, explicit-license, force-dot-license, recursive, no-replace,
-    # skip-unrecognized, skip-existing
+    # skip-unrecognized, and skip-existing.
     header.add_arguments(parser)
 
     git_root = check_reuse_dir()
@@ -198,7 +209,7 @@ def run_reuse(parser, year, loc, missing_headers):
 
 
 def main():
-    """Find files missing license header & run reuse on them."""
+    """Find files missing license headers and run `REUSE <https://reuse.software/>`_ on them."""
     return find_files_missing_header()