########################
byteb4rbie-sphinxcontrib
########################

A collection of general-purpose Sphinx extensions

Installation
============

via pip (PyPi)
--------------

.. code-block::

    $> python3 -m pip install byteb4rb1e-sphinxcontrib

via pip (Git)
-------------

.. code-block::

    $> python3 -m pip git+https://bitbucket.org/byteb4rb1e/sphinxcontrib@master

Usage
=====

.. toctree::
    :caption: Sphinx Extensions

    authorship
    authorship_svc
    svc

Installation (Development)
==========================

.. code-block::

    $> git clone https://bitbucket.org/byteb4rb1e/sphinxcontrib

.. warning::

    (Non-MSYS2) Windows users MUST use ``.venv/Scripts/python3.exe``, instead of
    ``.venv/bin/python3``

.. warning::

    (Non-MSYS2) Windows users MUST execute ``python3 -m pipenv install -d
    --skip-lock``, instead of ``sh ./configure``.

with pipenv
-----------

``pipenv`` expected to be installed system-wide

.. code-block::

    $> sh ./configure

with venv
---------

.. code-block::

    $> python3 -m venv --system-site-packages .venv
    $> .venv/bin/python3 -m pip install pipenv
    $> .venv/bin/python3 -m pipenv run sh ./configure

with venv (but without configuration)
-------------------------------------

.. code-block::

    $> python3 -m venv --system-site-packages .venv
    $> .venv/bin/python3 -m pip install -r requirements-dev.txt

Development
===========

Static Code Analysis
--------------------

.. code-block::

    $> python3 -m pipenv run test-static

Audit
~~~~~

.. code-block::

    $> python3 -m tox -e audit

Format
~~~~~~

.. code-block::

    $> python3 -m tox -e format -- --inline

Lint
~~~~

.. code-block::

    $> python3 -m tox -e lint


Unit Testing
------------

.. code-block::

    $> python3 -m pipenv run test-unit

Test Suite
~~~~~~~~~~

.. code-block::

    $> python3 -m pipenv run test-unit -- -p tests/unit

Test Case
~~~~~~~~~

.. code-block::

    $> python3 -m pipenv run test-unit -- -p tests/unit

Integration Testing
-------------------

.. code-block::

    $> python3 -m pipenv run test-integration

Test Suite
~~~~~~~~~~

.. code-block::

    $> python3 -m pipenv run test-integration -- \
        -p tests/integration/byteb4rb1e_sphinxcontrib/authorship

Test Case
~~~~~~~~~

.. code-block::

    $> python3 -m pipenv run test-integration -- \
        -p tests/integration/byteb4rb1e_sphinxcontrib/authorship/test_setup.py

with a definitive Python and Sphinx major version (e.g. *Python* ``3.10``, and *Sphinx*
``6``)

.. code-block::

    $> python3 -m tox -e py310-sphinx6-integration -- \
        -p tests/unit

Documentation
-------------

.. code-block::

    $> python3 -m pipenv run doc