https://github.com/BasicWolf/sphinx-testify

Testified Documentation plugin for Sphinx
https://github.com/BasicWolf/sphinx-testify

Last synced: 5 days ago
JSON representation

Testified Documentation plugin for Sphinx

• Host: GitHub
• URL: https://github.com/BasicWolf/sphinx-testify
• Owner: BasicWolf
• License: gpl-3.0
• Created: 2024-10-19T11:49:21.000Z (4 months ago)
• Default Branch: master
• Last Pushed: 2025-02-05T09:07:18.000Z (8 days ago)
• Last Synced: 2025-02-05T10:22:13.226Z (8 days ago)
• Language: Python
• Size: 119 KB
• Stars: 6
• Watchers: 1
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: COPYING

Awesome Lists containing this project

• awesome-python-testing - Sphinx-testify - Testified documentation means that the documentation source references test results, and these references are verified during the build process. As a result, we can keep every paragraph even every sentence of the documentation aligned with the code, as long as there is a test that "testifies" the described behaviour. (Testing Frameworks)

README

        
![Build](https://github.com/basicwolf/sphinx-testify/actions/workflows/ci.yml/badge.svg)

# Sphinx-testify

sphinx-testify is an extension to the Sphinx documentation generator,

that enables building [testified documentation][] and, ultimately

[living documentation][].

[testified documentation]: https://sphinx-testify.readthedocs.io/en/latest/testified-documentation.html

[living documentation]: https://gojko.net/books/specification-by-example/

## Testified documentation in a nutshell

Testified documentation means that the documentation source references test

results, and these references are verified during the build process.

As a result, we can keep every paragraph even every sentence of

the documentation aligned with the code, as long as there is a test

that "testifies" the described behaviour.

## A simple example

Imagine you're working on a system access module.

Even *before* writing any tests or code, you can briefly document

the expected behavior and reference the (to-be-created) tests.

Proceed with a TDD cycle, and once all the tests and implementation

are ready, you’ll have testified and living documentation.

Here's how it looks like in a reStructuredText document:

```rst

   System access

   =============

   Users with valid credentials: a username and a password can access

   the system. If credentials are wrong, the system returns "Authentication failed"

   error message.

   .. testify::

      test_a_user_can_access_system_with_username_and_password

      test_system_returns_authentication_failed_error_when_username_is_not_found

      test_system_returns_authentication_failed_error_when_password_is_wrong

```

## A full example

You practice what you preach. It would be hypocritical to develop sphinx-testify

in a way different from what is described above.

In short, the documentation to the library itself is testified!

Everything you need for a real-world example is here, in the repository :)

## Installation

```shell

pip install sphinx-testify

```

## Links

Code: https://github.com/BasicWolf/sphinx-testify




Docs: https://sphinx-testify.readthedocs.io/en/latest/

## License

GPLv3