docs: new house style

hynek · Oct 27, 2024 · 9fbfe4e · 9fbfe4e
1 parent b76a94b
commit 9fbfe4e
Show file tree

Hide file tree

Showing 5 changed files with 9 additions and 9 deletions.
diff --git a/docs/api.md b/docs/api.md
@@ -44,7 +44,7 @@
 ```
 
 
-## Activation and Deactivation
+## Activation and deactivation
 
 ```{eval-rst}
 .. autofunction:: set_active

diff --git a/docs/instrumentation.md b/docs/instrumentation.md
@@ -68,7 +68,7 @@ Use `structlog.stdlib.BoundLogger` and explicit async methods like `ainfo()` ins
 
 (logging)=
 
-## Standard Library's `logging`
+## Standard library's `logging`
 
 If standard library's `logging` integration is active, logging happens at warning level and includes the following *extra fields*:
 

diff --git a/docs/motivation.md b/docs/motivation.md
@@ -1,6 +1,6 @@
 # Motivation
 
-## The Need for Retries
+## The need for retries
 
 Retries are essential for making distributed systems resilient.
 Transient errors are unavoidable and can happen for the wildest reasons:
@@ -15,7 +15,7 @@ And sometimes, one never finds out because a [cosmic ray](https://en.wikipedia.o
 The bigger the scale, the more likely it is that something will go wrong -- but the chance is never zero.
 
 
-## The Dangers of Retries
+## The dangers of retries
 
 However, retries are also very dangerous if done naïvely.
 Simply repeating an operation until it succeeds can lead to [*cascading failures*](https://en.wikipedia.org/wiki/Cascading_failure) and [*thundering herds*](https://en.wikipedia.org/wiki/Thundering_herd_problem) and ultimately take down your whole system, just because a database had a brief hiccup.
@@ -60,7 +60,7 @@ You can [tune all these parameters](stamina.retry) to your liking, but the defau
 I hope you're now all motivated and ready to jump into our {doc}`tutorial`!
 
 
-## Supplemental Literature
+## Supplemental literature
 
 - The [*Exponential Backoff And Jitter*](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) article on the *AWS Architecture Blog* is a good explanation of the basics with pretty graphs.
 - [*Resiliency in Distributed Systems*](https://blog.pragmaticengineer.com/resiliency-in-distributed-systems/) takes a broader view and explains how to build resilient systems in general.

diff --git a/docs/testing.md b/docs/testing.md
@@ -3,7 +3,7 @@
 Testing code with retry logic can be tricky, so *stamina* provides dedicated testing helpers that allow you to affect retrying behavior *globally*.
 
 
-## Turn Off Retries
+## Turn off retries
 
 The easiest way is to turn off retries using {func}`stamina.set_active`:
 
@@ -19,7 +19,7 @@ def deactivate_retries():
 This is a great approach when you're only using our decorator-based API.
 
 
-## Limiting Retries
+## Limiting retries
 
 :::{versionadded} 24.3.0
 :::

diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -62,7 +62,7 @@ def do_it(code: int) -> httpx.Response:
 To give you observability of your application's retrying, *stamina* will count the retries using [*prometheus-client*](https://github.com/prometheus/client_python) in the `stamina_retries_total` counter (if installed) and log them out using [*structlog*](https://www.structlog.org/) with a fallback to {mod}`logging`.
 
 
-## Arbitrary Code Blocks
+## Arbitrary code blocks
 
 Sometimes you only want to retry a part of a function.
 
@@ -77,7 +77,7 @@ for attempt in stamina.retry_context(on=httpx.HTTPError):
 ```
 
 
-## Retry One Function or Method Call
+## Retry one function or method call
 
 If you want to retry just one function or method call, *stamina* comes with an even easier way in the shape of {class}`stamina.RetryingCaller` and {class}`stamina.AsyncRetryingCaller`: