Merge pull request #35 from 15r10nk/design

Design and documentation

.github/workflows/docs.yml

@@ -3,6 +3,7 @@ on:
   push:
     tags:
     - v[0-9]+.[0-9]+.[0-9]+
+    - deployed_docs
 
 jobs:
   build:
@@ -26,3 +27,8 @@ jobs:
           #EXTRA_PACKAGES: build-base
           # GITHUB_DOMAIN: github.myenterprise.com
         REQUIREMENTS: doc_requirements.txt
+    - name: tag docs
+      uses: tvdias/github-tagger@v0.0.1
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        tag: deployed_docs

README.md

@@ -1,10 +1,9 @@
-# inline-snapshot
-
+<!-- -8<- [start:Header] -->
 
 <p align="center">
-  <strong>
-create and update inline snapshots in your code.
-  </strong>
+  <a href="https://15r10nk.github.io/inline-snapshot/">
+    <img src="https://raw.githubusercontent.com/15r10nk/inline-snapshot/design/docs/assets/logo.svg" width="500" alt="inline-snapshot">
+  </a>
 </p>
 
 ![ci](https://github.com/15r10nk/inline-snapshot/actions/workflows/ci.yml/badge.svg?branch=main)
@@ -15,6 +14,8 @@ create and update inline snapshots in your code.
 [![coverage](https://img.shields.io/badge/coverage-100%25-blue)](https://15r10nk.github.io/inline-snapshot/contributing/#coverage)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/15r10nk)](https://github.com/sponsors/15r10nk)
 
+<!-- -8<- [end:Header] -->
+
 ## Installation
 
 You can install "inline-snapshot" via [pip](https://pypi.org/project/pip/):

docs/cmp_snapshot.md

@@ -2,40 +2,119 @@
 
 A snapshot can be compared against any value with `<=` or `>=`.
 This can be used to create a upper/lower bound for some result.
+The snapshot value can be trimmed to the lowest/largest valid value.
 
 Example:
 
-<!-- inline-snapshot: update this -->
-```python
-def some_algo():
-    ...
-    result = 42
-    iterations = 2
-    ...
-    return result, iterations
+=== "original code"
+    <!-- inline-snapshot: outcome-passed=1 outcome-errors=1 -->
+    ```python
+    def gcd(x, y):
+        iterations = 0
+        if x > y:
+            small = y
+        else:
+            small = x
+        for i in range(1, small + 1):
+            iterations += 1
+            if (x % i == 0) and (y % i == 0):
+                gcd = i
 
+        return gcd, iterations
 
-def test_something():
-    result, iterations = some_algo()
 
-    assert result == snapshot(42)
-    assert iterations <= snapshot(2)
-```
+    def test_gcd():
+        result, iterations = gcd(12, 18)
+
+        assert result == snapshot()
+        assert iterations <= snapshot()
+    ```
+
+=== "--inline-snapshot=create"
+    <!-- inline-snapshot: create -->
+    ```python
+    def gcd(x, y):
+        iterations = 0
+        if x > y:
+            small = y
+        else:
+            small = x
+        for i in range(1, small + 1):
+            iterations += 1
+            if (x % i == 0) and (y % i == 0):
+                gcd = i
+
+        return gcd, iterations
+
+
+    def test_gcd():
+        result, iterations = gcd(12, 18)
+
+        assert result == snapshot(6)
+        assert iterations <= snapshot(12)
+    ```
+
+=== "optimized code "
+    <!-- inline-snapshot: outcome-passed=1 -->
+    ```python
+    def gcd(x, y):
+        # use Euclidean Algorithm
+        iterations = 0
+        while y:
+            iterations += 1
+            x, y = y, x % y
+        return abs(x), iterations
+
+
+    def test_gcd():
+        result, iterations = gcd(12, 18)
+
+        assert result == snapshot(6)
+        assert iterations <= snapshot(12)
+    ```
+
+=== "--inline-snapshot=trim"
+    <!-- inline-snapshot: trim -->
+    ```python
+    def gcd(x, y):
+        # use Euclidean Algorithm
+        iterations = 0
+        while y:
+            iterations += 1
+            x, y = y, x % y
+        return abs(x), iterations
+
+
+    def test_gcd():
+        result, iterations = gcd(12, 18)
+
+        assert result == snapshot(6)
+        assert iterations <= snapshot(3)
+    ```
 
 !!! warning
     This should not be used to check for any flaky values like the runtime of some code, because it will randomly break your tests.
 
 The same snapshot value can also be used in multiple assertions.
-The snapshot value in the following case would be `6`.
 
-<!-- inline-snapshot: outcome-errors=1 outcome-passed=1 -->
-```python
-def test_something():
-    value = snapshot()
+=== "original code"
+    <!-- inline-snapshot: outcome-errors=1 outcome-passed=1 -->
+    ```python
+    def test_something():
+        value = snapshot()
+
+        assert 5 <= value
+        assert 6 <= value
+    ```
+=== "--inline-snapshot=create"
+    <!-- inline-snapshot: create -->
+    ```python
+    def test_something():
+        value = snapshot(6)
 
-    assert 5 <= value
-    assert 6 <= value
-```
+        assert 5 <= value
+        assert 6 <= value
+    ```
 
 ## pytest options
 

docs/eq_snapshot.md

@@ -5,11 +5,19 @@ The value gets recorded if the snapshot is undefined (`snapshot()`)
 
 Example:
 
-<!-- inline-snapshot: update this -->
-```python
-def test_something():
-    assert 2 + 2 == snapshot(4)
-```
+=== "original code"
+    <!-- inline-snapshot: outcome-passed=1 outcome-errors=1 -->
+    ```python
+    def test_something():
+        assert 2 + 2 == snapshot()
+    ```
+
+=== "--inline-snapshot=create"
+    <!-- inline-snapshot: create -->
+    ```python
+    def test_something():
+        assert 2 + 2 == snapshot(4)
+    ```
 
 ## pytest options