Setup

Setting up developer environment

autodoc_pydantic uses poetry for environment and package management.

Cloning repository

git clone https://github.com/mansenfranzen/autodoc_pydantic.git
cd autodoc_pydantic

Creating environment

poetry install --all-extras

Running & writing tests

pytest

To quickly execute the test suite within your current developer environment with pytest, run poetry run pytest.

tox

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: 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.

Note

Using tox has the benefit of completing the entire build-deploy-test-cycle:

  1. build source distribution from pyproject.toml

  2. create specified virtual environment for test execution

  3. install source distribution in virtual environment

  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

autodoc_pydantic’s documentation is generated with sphinx . To generate the HTML documentation, please use the following:

poetry shell
cd docs
make clean && make html

The generated documentation can be found under docs/build/html/index.html.

This documentation was built with the following environment:

sphinx:

7.2.6

pydantic:

2.7.0

sphinx-rtd-theme:

2.0.0

sphinx-tabs:

3.4.5

sphinx-copybutton:

0.5.2

sphinxcontrib-mermaid:

7.2.6