167 lines
2.6 KiB
ReStructuredText
167 lines
2.6 KiB
ReStructuredText
########################
|
|
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
|
|
|