ceddlyburge / docs-from-tests-example

This is a demonstration repo, showing how to use the docs-from-tests python package.

Example usage of "docs-from-tests" package

This is a demonstration repo, showing how to use the docs-from-tests python package. More background on why should want to do this are in the How to Create Documentation from Your Python Tests blog post.

The package contains functions to instrument your code / tests to create a sequence diagram (in markdown / mermaid) as the tests run. The sequence diagrams show the runtime call hierachy of the code, and are saved as files in the repository, which are checked in. You can choose to ignore specific functions, and private functions, to make the diagram readable in each context you are interested in.

The diagrams are useful documentation, and will stay up to date as they are automatically generated. Hopefully it will encourage us to have useful diagrams in the repo, with the appropriate levels of detail, which in turn will encourage us to structure the code well so it produces good diagrams, and to have tests at these levels of detail.

Build Status

Example Usage

You can see an example of generating documentation from tests at tests\test_hello_world.py

There is an end to end test, and a unit test, and they produce the documentation / graphs below

• doc/end-to-end-sequence-diagram.md
• doc/world-sequence-diagram.md

The graphs are reproduced here for convenience. They are mermaid diagrams, you may need to install a Browser Plugin or VsCode extension or similar to view them.

End to end

View full screen as an SVG

sequenceDiagram
  start->>HelloWorldCombiner.combine: calls x1
  HelloWorldCombiner.combine->>hello: calls x1
  hello-->>HelloWorldCombiner.combine: returns str
  HelloWorldCombiner.combine->>World.world: calls x1
  World.world-->>HelloWorldCombiner.combine: returns str
  HelloWorldCombiner.combine-->>start: returns str

Unit test

View full screen as SVG

sequenceDiagram
  start->>World.world: calls x1
  World.world->>World._w: calls x1
  World._w-->>World.world: returns str
  World.world->>World._o: calls x1
  World._o-->>World.world: returns str
  World.world->>World._r: calls x1
  World._r-->>World.world: returns str
  World.world->>World._l: calls x1
  World._l-->>World.world: returns str
  World.world->>World._d: calls x1
  World._d-->>World.world: returns str
  World.world-->>start: returns str

Running tests

• use python>=3.7
• pip install requirements.txt
• set pythonpath=<path to root of this repo>
• pytest

Contributing

• Use PEP-0008
• Please open up an Issue for new work, where any discussion can take place, and then submit a pull request to fix the issue.