From 6c2df76dc14453bd97d17b30d28805e0b2219e96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Franz=20W=C3=B6llert?= Date: Thu, 21 Mar 2024 12:46:29 +0100 Subject: [PATCH] Update poetry and setup docs --- docs/source/developers/setup.rst | 38 ++++++++++++++++---------------- pyproject.toml | 23 +++++++++---------- 2 files changed, 30 insertions(+), 31 deletions(-) diff --git a/docs/source/developers/setup.rst b/docs/source/developers/setup.rst index 7faece55..3eb7f6d9 100644 --- a/docs/source/developers/setup.rst +++ b/docs/source/developers/setup.rst @@ -20,24 +20,13 @@ Cloning repository git clone https://github.com/mansenfranzen/autodoc_pydantic.git cd autodoc_pydantic -.. note:: - - In June 2023, **pydantic v2** was released. This introduced backwards - incompatible API and behavioral changes in comparison to pydantic v1. Hence, - **autodoc_pydantic** required substantial adjustments, too. In order to keep - the codebase clean and concise, separate versions for v1 and v2 were - created. The v2 branch will eventually become the new `main`_ branch while - the code for v1 remains in the `main-1.x`_ branch. - - In a nutshell, if you want to work on v1, please checkout the corresponding - `main-1.x`_ branch. Otherwise, refer to the `main`_ branch. Creating environment -------------------- .. code-block:: bash - poetry install -E dev -E erdantic + poetry install --all-extras ----------------------- Running & writing tests @@ -52,14 +41,24 @@ with pytest, run ``poetry run pytest``. tox --- -For more sophisticated testing, you can use tox for different test -environments. A test environment is characterized by varying versions of -*autodoc_pydantic*'s dependencies like pydantic, sphinx and sphinx-tabs: +For more sophisticated testing, use `tox `_ +for different test environments. Test environments are characterized +by varying versions of python and *autodoc_pydantic*'s dependencies +like pydantic and sphinx. This is critical for ensuring library +compatibility across different versions of python and pydantic and +sphinx. + +**Usage:** + +First, make sure you have tox installed globally via ``pipx`` or ``pip`` +(see `here `_): + +Second, to invoke the test suite with tox, run one of the following commands: -- Test a specific environment: ``poetry run tox -e py38-pydantic17-sphinx34`` -- Test the latest stable versions from pypi: ``poetry run tox -e latest`` -- Test the current developer versions from git repositories: ``poetry run tox -e development`` -- Test all available environments: ``poetry run tox`` (not recommended) +- Test a specific environment: ``tox -e py311-pydantic26-sphinx71`` +- Test the latest stable versions from pypi: ``tox -e latest`` +- Test the current developer versions from git repositories: ``tox -e development`` +- Test all available environments: ``tox`` (not recommended) Please visit the ``tox.ini`` for all available test environments. @@ -73,6 +72,7 @@ Please visit the ``tox.ini`` for all available test environments. 4. run tests within virtual environment via pytest 5. provide test coverage report + This approach is chosen in the corresponding CI/CD pipeline. ----------------------- Building & writing docs diff --git a/pyproject.toml b/pyproject.toml index 05500266..f38b27f3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -24,17 +24,24 @@ python = ">=3.8,<4.0.0" Sphinx = ">=4.0" pydantic = ">=2.0,<3.0.0" pydantic-settings = ">=2.0,<3.0.0" - importlib-metadata = { version = ">1", markers = "python_version <= '3.8'" } +# poetry dependency groups are not used on purpose because they are not natively +# supported with tox. Hence, test/doc dependencies are managed via extras. +# See https://github.com/orgs/python-poetry/discussions/4307 + +# extras docs sphinx-rtd-theme = { version = "^1.0", optional = true } sphinx-tabs = { version = "^3", optional = true } sphinx-copybutton = { version = "^0.4", optional = true } sphinxcontrib-mermaid = { version = "^0.7", optional = true } + +# extras tests pytest = {version = "^7", optional = true } coverage = { version ="^7", optional = true } flake8 = { version = "^3", optional = true } -tox = { version ="^3", optional = true } + +# extras erdantic erdantic = { version ="^0.6", optional = true } [tool.pytest.ini_options] @@ -47,16 +54,8 @@ docs = ["sphinx-rtd-theme", "sphinxcontrib-mermaid"] test = ["pytest", - "coverage"] - -dev = ["pytest", - "coverage", - "sphinx-rtd-theme", - "sphinx-tabs", - "sphinx-copybutton", - "sphinxcontrib-mermaid", - "flake8", - "tox"] + "coverage", + "flake8"] erdantic = ["erdantic"]