Merge pull request #4 from JerilynFranz/doc-fixes

Updated documenation

Author: JerilynFranz

docs_source/configuration.rst

@@ -5,7 +5,7 @@ Configuration
 autopypath can be configured in several ways to suit different project structures
 and user preferences. The configuration sources include:
 
-- Configuration files: `autopypath.toml` and `pyproject.toml`.
+- Configuration files: ``autopypath.toml`` and ``pyproject.toml``.
 - Function parameters: Directly passing configuration options to the `configure_pypath()` function.
 - Default settings: Built-in defaults used when no other configuration is provided.
 
@@ -16,9 +16,9 @@ By default, autopypath identifies the repository root by looking for specific
 marker files or directories. The default markers are:
 
 - ``autopypath.toml``: A configuration file that can specify custom repository
-  root markers in addition to other settings. Only the first autopypath.toml file
-  found when searching upwards from the starting directory is used. Additional autopypath.toml files
-  found higher up the directory tree are ignored.
+  root markers in addition to other settings. Only the first ``autopypath.toml`` file
+  found when searching upwards from the starting directory is used. Additional
+  ``autopypath.toml`` files found higher up the directory tree are ignored.
 - ``pyproject.toml``: A common project configuration file that can also
   contain autopypath settings.
 - ``.git``: Indicates a Git repository root by the presence of this directory.
@@ -34,10 +34,10 @@ root of the repository. Autopypath searches upwards from the starting directory
 until it finds one of these markers.
 
 It is possible to customize the repository root markers by providing a
-list of marker names to the `repo_markers` parameter of the `configure_pypath()`
-function or by specifying them in the `autopypath.toml` configuration file.
+list of marker names to the ``repo_markers`` parameter of the ``configure_pypath()``
+function or by specifying them in the ``autopypath.toml`` configuration file.
 
-Example of customizing repository root markers in `autopypath.toml` or `pyproject.toml`:
+Example of customizing repository root markers in ``autopypath.toml`` or ``pyproject.toml``:
 
 .. code-block:: toml
 
@@ -48,73 +48,73 @@ Example of customizing repository root markers in `autopypath.toml` or `pyprojec
 Load Strategy
 =============
 
-Load Strategy determines how found paths are added to `sys.path`. The default
-strategy is `prepend`, but it can be customized using the `load_strategy` parameter
-to `configure_pypath()` or configured in `pyproject.toml`` file in the repository root, or in
-an `autopypath.toml` file.
+Load Strategy determines how found paths are added to :data:`sys.path`. The default
+strategy is ``prepend``, but it can be customized using the ``load_strategy`` parameter
+to `configure_pypath()` or configured in ``pyproject.toml`` file in the repository root, or in
+an ``autopypath.toml`` file.
 
 The available load strategies are:
 
 prepend
 -------
 
-`prepend` adds merged found paths to the start of `sys.path`
+``prepend`` adds merged found paths to the start of :data:`sys.path`
 in precedence resolution ordered from highest to lowest. This ensures that
 modules in the repository take precedence over globally installed modules.
 
-prepend_highest_only
+prepend_highest_priority
 --------------------
 
-`prepend_highest_only` adds only the highest precedence found path to the start of `sys.path`.
+``prepend_highest_priority`` adds only the highest precedence found path to the start of :data:`sys.path`.
 This is useful when you want to ensure that only the most relevant path is used.
 
 replace
 -------
 
-`replace` clears `sys.path` and adds only the found paths. This is useful for isolated environments
+``replace`` clears :data:`sys.path` and adds only the found paths. This is useful for isolated environments
 where you want to avoid any interference from globally installed modules. This
 is a highly advanced use case and should be used with **extreme** caution as it will remove all
-other paths from `sys.path` - including standard library paths.
+other paths from :data:`sys.path` - including standard library paths.
 
 .. warning::
 
     This **WILL** break many Python functionalities and is in the category of "if you don't know why you need it,
     you don't need it". Expert users only!
 
-The load strategy can be set in either `pyproject.toml` or `autopypath.toml` like this:
+The load strategy can be set in either ``pyproject.toml`` or ``autopypath.toml`` like this:
 
 .. code-block:: toml
   :caption: pyproject.toml or autopypath.toml
 
     [tool.autopypath]
-    load_strategy = "prepend"  # or "prepend_highest_only" or "replace"
+    load_strategy = "prepend"  # or "prepend_highest_priority" or "replace"
 
 Paths
 =====
 
-By default, autopypath adds several common project directories to `sys.path`
+By default, autopypath adds several common project directories to :data:`sys.path`
 relative to the repository root. These default paths are intended to cover
 the most common project layouts. The default paths, in order of priority, are:
 
-- `src`: Common source directory for project code.
-- `tests`: Common source directory for test code.
-- `lib`: Common source directory for library code.
-- `src/test`: Alternate test source directory.
+- ``src``: Common source directory for project code.
+- ``tests``: Common source directory for test code.
+- ``lib``: Common source directory for library code.
+- ``src/test``: Alternate test source directory.
 
 These directories are added to :data:`sys.path` if they exist in the repository root -
 but only if no other paths are provided.
 
-You can customize the paths added to `sys.path` using the `paths` parameter
-to `configure_pypath()`, in a `pyproject.toml`, or a `autopypath.toml` file
-in the `[tool.autopypath]` section.
+You can customize the paths added to :data:`sys.path` using the ``paths`` parameter
+to `configure_pypath()`, in a ``pyproject.toml``, or a ``autopypath.toml`` file
+in the ``[tool.autopypath]`` section.
 
 This is just the 'out-of-the-box' default configuration and is intended to cover
 the most common project layouts. You can (and **should**) customize it as needed for your project.
 
 
 If a configured path does not exist or is not a directory, it will be logged at 'INFO' level and skipped.
 
-In either `pyproject.toml` or `autopypath.toml`, the configuration for paths looks like this:
+In either ``pyproject.toml`` or ``autopypath.toml``, the configuration for paths looks like this:
 
 .. code-block:: toml
 
@@ -125,28 +125,27 @@ Path Resolution Order
 =====================
 
 The order in which autopypath resolves paths can be customized using the
-`path_resolution_order` parameter to `configure_pypath()` or in a
-`pyproject.toml` or `autopypath.toml` file. This setting determines the sequence
-of configuration sources that autopypath checks for paths to add to `sys.path`.
+``path_resolution_order`` parameter to `configure_pypath()` or in a
+``pyproject.toml`` or ``autopypath.toml`` file. This setting determines the sequence
+of configuration sources that autopypath checks for paths to add to :data:`sys.path`.
 
 The available sources are:
 
-- `manual`: Paths provided directly via the `paths` parameter to `configure_pypath()`.
-- `autopypath`: Paths specified in `autopypath.toml` configuration files.
-- `pyproject`: Paths specified in `pyproject.toml` configuration files.
+- ``manual``: Paths provided directly via the ``paths`` parameter to `configure_pypath()`.
+- ``autopypath``: Paths specified in ``autopypath.toml`` configuration files.
+- ``pyproject``: Paths specified in ``pyproject.toml`` configuration files.
 
-The default resolution order is `['manual', 'autopypath', 'pyproject']`, meaning
-that manually provided paths take precedence over those specified in `autopypath.toml`,
-which in turn take precedence over those in `pyproject.toml`. '
+The default resolution order is ``['manual', 'autopypath', 'pyproject']``, meaning
+that manually provided paths take precedence over those specified in ``autopypath.toml``,
+which in turn take precedence over those in ``pyproject.toml``.
 
-This primarily affect the order in which paths are added to `sys.path` when using
-the `prepend` load strategy.
+This primarily affects the order in which paths are added to :data:`sys.path` when using
+the ``prepend`` load strategy.
 
-In either `pyproject.toml` or `autopypath.toml`, the configuration for path resolution
+In either ``pyproject.toml`` or ``autopypath.toml``, the configuration for path resolution
 order looks like this:
 
 .. code-block:: toml
 
     [tool.autopypath]
     path_resolution_order = ["manual", "autopypath", "pyproject"]
-

docs_source/contributing.rst

@@ -42,15 +42,15 @@ To contribute code or documentation updates to `autopypath`, follow these steps:
        cd python-autopypath 
 
 4. Create a new branch for your changes. Please use descriptive names for your branches
-   to indicate the purpose of your changes such as `feature/my-feature-branch` or
-   `fix/issue-123`, `docs/update-readme`, etc.
+   to indicate the purpose of your changes such as ``feature/my-feature-branch`` or
+   ``fix/issue-123``, ``docs/update-readme``, etc.
 
    .. code-block:: shell
 
        git checkout -b feature/my-feature-branch
 
 5. Setup the development environment as described in the :ref:`development-installation` section
-   by running the `bootstrap.py` script and activating the virtual environment.
+   by running the ``bootstrap.py`` script and activating the virtual environment.
 
    This will install all necessary dependencies for development and testing including current versions of
    `tox <https://python-basics-tutorial.readthedocs.io/en/latest/test/tox.html>`_, `ruff <https://ruff.rs/>`_,
@@ -61,7 +61,7 @@ To contribute code or documentation updates to `autopypath`, follow these steps:
 
        python bootstrap.py
 
-   .. code-block:: text
+   .. code-block:: shell
      :caption: Activating the virtual environment on Linux/macOS
 
        source .venv/bin/activate
@@ -71,22 +71,28 @@ To contribute code or documentation updates to `autopypath`, follow these steps:
 
        .venv\Scripts\activate.bat
 
+   .. code-block:: text
+     :caption: Activating the virtual environment on Windows PowerShell
+
+       .venv\Scripts\Activate.ps1
+
 6. Make your changes and test them thoroughly using the existing test suite
    and by adding new tests if necessary. Our goal is to maintain high code quality
    and ensure that all code is tested and all tests pass before merging any contributions.
 
    We use `ruff <https://ruff.rs/>`_ and `mypy <https://mypy.readthedocs.io/en/stable/>`_ for linting,
    code style, and type checking, so please ensure your code adheres to the project's coding standards.
-   This is largely automated via `tox` and the `tox` configuration already includes `ruff` and `mypy` checks
+   This is largely automated via `tox <https://python-basics-tutorial.readthedocs.io/en/latest/test/tox.html>`_
+   and the ``tox`` configuration already includes `ruff <https://ruff.rs/>`_ and `mypy <https://mypy.readthedocs.io/en/stable/>`_ checks
    as part of the test suite.
 
    If the tests don't pass or don't cover your changes, the pull request may be delayed or rejected.
 
-   You can run the test suite using `tox`:
+   You can run the test suite using ``tox``:
 
    .. code-block:: shell
 
-       tox
+       tox run
 
    It checks your code against multiple Python versions and runs all tests to ensure compatibility
    and correctness.
@@ -100,8 +106,8 @@ To contribute code or documentation updates to `autopypath`, follow these steps:
    the source files are located in the `docs_source <https://github.com/JerilynFranz/python-autopypath/tree/main/docs_source>`_
    directory of the project.
 
-   You can locally build the documentation using `tox run -e docs` to verify your changes.
-   The built documentation will be available in the `documentation` directory.   
+   You can locally build the documentation using ``tox run -e docs`` to verify your changes.
+   The built documentation will be available in the ``documentation`` directory.   
 
    .. code-block:: shell
 
@@ -113,7 +119,7 @@ To contribute code or documentation updates to `autopypath`, follow these steps:
 
        git push origin my-feature-branch
 
-9.  Open a pull request on the `python-autopypath` repository.
+9.  Open a pull request on the ``python-autopypath`` repository.
 
     Make sure to provide a clear description of your changes, the problem they solve,
     and any relevant context. Link to any related issues if applicable.
@@ -139,7 +145,7 @@ To contribute code or documentation updates to `autopypath`, follow these steps:
 uv.lock
 -------
 
-uv.lock is included in the source distribution to support reproducible
+``uv.lock`` is included in the source distribution to support reproducible
 builds and independent verification. Use of uv is optional for contributors.
 
 Need Help?

docs_source/installation.rst

@@ -20,8 +20,8 @@ repository and install it manually. Here are the steps to do so:
 
 .. code-block:: shell
 
-   git clone https://github.com/JerilynFranz/autopypath.git
-   cd autopypath
+   git clone https://github.com/JerilynFranz/python-autopypath.git
+   cd python-autopypath
    pip install .
 
 .. _development-installation:
@@ -39,12 +39,33 @@ To make this easier, a bootstrap script is provided.
 You can run the following commands:
 
 .. code-block:: shell
+   :caption: Setting up the development environment
 
    git clone https://github.com/JerilynFranz/python-autopypath.git
    cd python-autopypath
-   python3 bootstrap.py
+   python bootstrap.py
+
+And then activate the virtual environment with:
+
+.. code-block:: shell
+   :caption: Activating the virtual environment on Linux/macOS
+
    source .venv/bin/activate
 
+or on Windows use:
+
+.. code-block:: text
+   :caption: Activating the virtual environment on Windows
+
+   .venv\Scripts\activate.bat
+   
+or if using PowerShell:
+
+.. code-block:: text
+   :caption: Activating the virtual environment on Windows PowerShell
+
+   .venv\Scripts\Activate.ps1
+
 This will set up the development environment and install `autopypath` in
 editable mode.
 

docs_source/public_api.rst

@@ -126,7 +126,7 @@ configure_pypath
 
     :param strict:
         If `True`, raises an error for conditions that would normally only log a warning.
-        Default is `False`. It also turns logged warnings into logged errors and raised
+        Default is `False`. It also turns logged warnings into logged errors and raises
         :class:`~autopypath.custom.AutopypathError` exceptions.
 
         Conditions that normally trigger logged warnings include:
@@ -165,7 +165,7 @@ pyproject.toml and autopypath.toml Configurations and Defaults
 
 For information on configuring `autopypath` using `pyproject.toml` or
 `autopypath.toml` files, and for the defaults used when no configurations
-are explicitly set, please refer to the :ref:`configuration section <configuration>`
+are explicitly set, please refer to the :doc:`configuration section <configuration>`
 of the documentation.
 
 Logging