docs: new title house style

.github/CONTRIBUTING.md

@@ -45,7 +45,7 @@ It's people like *you* who make this project such a great tool for everyone.
 - Don't break [backwards-compatibility](SECURITY.md).
 
 
-## Local Development Environment
+## Local development environment
 
 First, **fork** the repository on GitHub and **clone** it using one of the alternatives that you can copy-paste by pressing the big green button labeled `<> Code`.
 
@@ -224,7 +224,7 @@ If your change is interesting to end-users, there needs to be an entry in our `C
   ```
 
 
-## See You on GitHub!
+## See you on GitHub!
 
 Again, this whole file is mainly to help you to get started by codifying tribal knowledge and expectations to save you time and turnarounds.
 It is **not** meant to be a barrier to entry, so don't be afraid to open half-finished PRs and ask questions if something is unclear!

.github/SECURITY.md

@@ -1,6 +1,6 @@
 # Security Policy
 
-## Supported Versions
+## Supported versions
 
 We are following [*CalVer*](https://calver.org) with generous backwards-compatibility guarantees.
 Therefore we only support the latest version.
@@ -13,7 +13,7 @@ They may be adjusted in the future to provide a better experience when starting
 So please make sure to **always** properly configure your applications.
 
 
-## Reporting a Vulnerability
+## Reporting a vulnerability
 
 To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
 Tidelift will coordinate the fix and disclosure.

docs/bound-loggers.md

@@ -65,7 +65,7 @@ Whenever you call one of those methods on the *bound logger*, it will:
 [^str]: {any}`str`, {any}`bytes`, or {any}`bytearray` to be exact.
 
 
-### Step-by-Step Example
+### Step-by-Step example
 
 Assuming you've left the default configuration and have:
 
@@ -103,7 +103,7 @@ If you call `log.info("Hello, %s!", "world", number=42)` now, the following happ
 
 (filtering)=
 
-## Filtering by Log Levels
+## Filtering by log levels
 
 Filtering based on log levels can be done in a processor very easily[^stdlib], however that means unnecessary performance overhead through function calls.
 We care a lot about performance and that's why *structlog*'s default *bound logger* class implements level-filtering as close to the users as possible: in the *bound logger*'s logging methods *before* even creating an *event dict* and starting the processor chain.
@@ -146,7 +146,7 @@ Passing `20` instead of `logging.INFO` would have worked too.
 [^stdlib]: And it's in fact supported for standard library logging with the {func}`structlog.stdlib.filter_by_level` processor.
 
 
-## Wrapping Loggers Manually
+## Wrapping loggers manually
 
 In practice, you won't be instantiating bound loggers yourself.
 You will configure *structlog* as explained in the {doc}`next chapter <configuration>` and then just call {func}`structlog.get_logger`.

docs/configuration.md

@@ -51,12 +51,12 @@ See also {doc}`performance`.
 :::
 
 
-## What To Configure
+## What to configure
 
 You can find the details in the API documentation of {func}`structlog.configure`, but let's introduce the most important ones at a high level first.
 
 
-### Wrapper Classes
+### Wrapper classes
 
 You've met {doc}`bound-loggers` in the last chapter.
 They're the objects returned by {func}`~structlog.get_logger` and allow to bind key-value pairs into their private context.
@@ -65,7 +65,7 @@ You can configure their type using the `wrapper_class` keyword.
 Whenever you bind or unbind data to a *bound logger*, this class is instantiated with the new context and returned.
 
 
-### Logger Factories
+### Logger factories
 
 We've already talked about wrapped loggers responsible for the output, but we haven't explained where they come from until now.
 Unlike with *bound loggers*, you often need more flexibility when instantiating them.

docs/console-output.md

@@ -34,7 +34,7 @@ For the console and beyond.
 
 (columns-config)=
 
-## Console Output Configuration
+## Console output configuration
 
 :::{versionadded} 23.3.0
 :::
@@ -106,7 +106,7 @@ structlog.configure(processors=structlog.get_config()["processors"][:-1]+[cr])
 :::
 
 
-## Standard Environment Variables
+## Standard environment variables
 
 *structlog*'s default configuration uses colors if standard out is a TTY (that is, an interactive session).
 
@@ -117,6 +117,6 @@ It's possible to override this behavior by setting two standard environment vari
   Please note that `NO_COLOR` disables _all_ styling, including bold and italics.
 
 
-## Disabling Exception Pretty-Printing
+## Disabling exception pretty-printing
 
 If you prefer the default terse Exception rendering, but still want Rich installed, you can disable the pretty-printing by instantiating {class}`structlog.dev.ConsoleRenderer()` yourself and passing `exception_formatter=structlog.dev.plain_traceback`.

docs/contextvars.md

@@ -101,7 +101,7 @@ def _helper():
 
 (flask-example)=
 
-## Example: Flask and Thread-Local Data
+## Example: Flask and thread-local data
 
 Let's assume you want to bind a unique request ID, the URL path, and the peer's IP to every log entry by storing it in thread-local storage that is managed by context variables:
 

docs/exceptions.md

@@ -27,7 +27,7 @@ The most common use-cases are already covered by the following processors:
 : Uses {class}`structlog.tracebacks.ExceptionDictTransformer` to give you a structured and JSON-serializable `exception` key.
 
 
-## Console Rendering
+## Console rendering
 
 Our {doc}`console-output`'s {class}`structlog.dev.ConsoleRenderer` takes an *exception_formatter* argument that allows for customizing the output of exceptions.
 

docs/getting-started.md

@@ -16,7 +16,7 @@ Try both to find out which one you like better -- the screenshot in the README a
 On **Windows**, you also have to install [Colorama](https://pypi.org/project/colorama/) if you want colorful output beside exceptions.
 
 
-## Your First Log Entry
+## Your first log entry
 
 A lot of effort went into making *structlog* accessible without reading pages of documentation.
 As a result, the simplest possible usage looks like this:
@@ -81,7 +81,7 @@ So let's go a step further.
 
 (building-ctx)=
 
-## Building a Context
+## Building a context
 
 Imagine a hypothetical web application that wants to log out all relevant data with just the APIs that we've introduced so far:
 
@@ -167,7 +167,7 @@ For that, *structlog* gives you thread-local context storage based on the {mod}`
 See {doc}`contextvars` for more information and a more complete example.
 
 
-## Manipulating Log Entries in Flight
+## Manipulating log entries in flight
 
 Now that your log events are dictionaries, it's also much easier to manipulate them than if they were plain strings.
 
@@ -212,7 +212,7 @@ So assuming you want to follow [best practices](logging-best-practices.md) and r
 ```
 
 
-## *structlog* and Standard Library's `logging`
+## *structlog* and standard library's `logging`
 
 While *structlog*'s loggers are very fast and sufficient for the majority of our users, you're not bound to them.
 Instead, it's been designed from day one to wrap your *existing* loggers and **add** *structure* and *incremental context building* to them.

docs/index.md

@@ -62,7 +62,7 @@ exceptions
 ```
 
 
-## Development Affordances
+## Development affordances
 
 *structlog*'s focus is on production systems, but it comes with **pretty console logging** and handy in-development helpers both for your **comfort** and your code's **quality**.
 
@@ -77,7 +77,7 @@ typing
 
 (integration)=
 
-## Integration with Existing Systems
+## Integration with existing systems
 
 *structlog* is both zero-config as well as highly configurable.
 You can use it on its own or integrate with existing systems.
@@ -93,7 +93,7 @@ twisted
 ```
 
 
-## *structlog* in Practice
+## *structlog* in practice
 
 The following chapters deal with considerations of using *structlog* in the real world.
 
@@ -121,7 +121,7 @@ modindex
 ```
 
 
-## Deprecated Features
+## Deprecated features
 
 ```{toctree}
 :maxdepth: 1

docs/logging-best-practices.md

@@ -14,7 +14,7 @@ It doesn't matter where or how your application runs -- it just works, and the r
 [^unix]: This is obviously a privileged UNIX-centric view but even Windows has tools and means for log management although we won't be able to discuss them here.
 
 
-## Canonical Log Lines
+## Canonical log lines
 
 Generally speaking, having as few log entries per request as possible is a good thing.
 The less noise, the more insights.
@@ -24,7 +24,7 @@ The less noise, the more insights.
 At Stripe, this concept is called [Canonical Log Lines](https://brandur.org/canonical-log-lines).
 
 
-## Pretty Printing vs. Structured Output
+## Pretty printing vs. structured output
 
 Colorful and pretty printed log messages are nice during development when you locally run your code.
 
@@ -61,7 +61,7 @@ Here is a simple example of how you can have pretty logs during development and
 ```
 
 
-## Centralized Logging
+## Centralized logging
 
 Nowadays you usually don't want your log files in compressed archives distributed over dozens -- if not thousands -- of servers or cluster nodes.
 You want them in a single location.

docs/processors.md

@@ -124,7 +124,7 @@ It does **not** use the standard library, but it does use its names and order of
 
 (adapting)=
 
-## Adapting and Rendering
+## Adapting and rendering
 
 An important role is played by the *last* processor because its duty is to adapt the `event_dict` into something the logging methods of the *wrapped logger* understand.
 With that, it's also the *only* processor that needs to know anything about the underlying system.
@@ -156,7 +156,7 @@ Advanced log aggregation and analysis tools like [*Logstash*](https://www.elasti
 For a list of shipped processors, check out the {ref}`API documentation <procs>`.
 
 
-## Third-Party Packages
+## Third-Party packages
 
 *structlog* was specifically designed to be as composable and reusable as possible, so whatever you're missing:
 chances are, you can solve it with a processor!

docs/recipes.md

@@ -7,7 +7,7 @@ Please note that recipes related to integration with frameworks have an [own cha
 
 (rename-event)=
 
-## Renaming the `event` Key
+## Renaming the `event` key
 
 The name of the event is hard-coded in *structlog* to `event`.
 But that doesn't mean it has to be called that in your logs.
@@ -23,7 +23,7 @@ With the {class}`structlog.processors.EventRenamer` processor, you can, for inst
 
 (finer-filtering)=
 
-## Fine-Grained Log-Level Filtering
+## Fine-grained log-level filtering
 
 *structlog*'s native log levels as provided by {func}`structlog.make_filtering_bound_logger` only know **one** log level – the one that is passed to `make_filtering_bound_logger()`.
 Sometimes, that can be a bit too coarse, though.
@@ -78,7 +78,7 @@ Pick the data you're interested in from the {class}`structlog.processors.Callsit
 
 (custom-wrappers)=
 
-## Custom Wrappers
+## Custom wrappers
 
 ```{testsetup}
 import structlog
@@ -141,7 +141,7 @@ These two methods and one attribute are all you need to write own *bound loggers
 [dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
 
 
-## Passing Context to Worker Threads
+## Passing context to worker threads
 
 Thread-local context data based on [context variables](contextvars.md) is -- as the name says -- local to the thread that binds it.
 When using threads to process work in parallel, you have to pass the thread-local context **into** the worker threads.
@@ -188,7 +188,7 @@ def manager(request_id: str):
 See the [issue 425](https://github.com/hynek/structlog/issues/425) for a more complete example.
 
 
-## Switching Console Output to Standard Error
+## Switching console output to standard error
 
 When using structlog without standard library integration and want the log output to go to standard error (*stderr*) instead of standard out (*stdout*), you can switch with a single line of configuration:
 

docs/standard-library.md

@@ -12,7 +12,7 @@ It will recreate the default configuration on top of `logging` and optionally co
 :::
 
 
-## Just Enough `logging`
+## Just enough `logging`
 
 If you want to use *structlog* with `logging`, you should have at least a fleeting understanding on how the standard library operates because *structlog* will *not* do any magic things in the background for you.
 Most importantly you have to *configure* the `logging` system *additionally* to configuring *structlog*.
@@ -35,7 +35,7 @@ This will send all log messages with the [log level](https://docs.python.org/3/l
 If you require more complex behavior, please refer to the standard library's `logging` documentation.
 
 
-## Concrete Bound Logger
+## Concrete bound logger
 
 *structlog* ships a stdlib-specific [*bound logger*](bound-loggers.md) that  mirrors the log methods of standard library's {any}`logging.Logger` with correct type hints.
 
@@ -125,7 +125,7 @@ To use it, {doc}`configure <configuration>` *structlog* to use `AsyncBoundLogger
 
 (stdlib-config)=
 
-## Suggested Configurations
+## Suggested configurations
 
 :::{note}
 We do appreciate that fully integrating *structlog* with standard library's `logging` is fiddly when done for the first time.
@@ -137,7 +137,7 @@ However, once it is set up, you can rely on not having to ever touch it again.
 Depending *where* you'd like to do your formatting, you can take one of four approaches:
 
 
-### Don't Integrate
+### Don't integrate
 
 The most straight-forward option is to configure standard library `logging` close enough to what *structlog* is logging and leaving it at that.
 
@@ -155,7 +155,7 @@ This can cause interleaving of log entries from *structlog* and `logging` logger
 :::
 
 
-### Rendering Within *structlog*
+### Rendering within *structlog*
 
 This is the simplest approach where *structlog* does all the heavy lifting and passes a fully-formatted string to `logging`.
 Chances are, this is all you need.
@@ -250,7 +250,7 @@ hello
 ```
 
 
-### Rendering Using `logging`-based Formatters
+### Rendering using `logging`-based formatters
 
 You can choose to use *structlog* only for building the event dictionary and leave all formatting -- additionally to the output -- to the standard library.
 
@@ -328,7 +328,7 @@ Keep this in mind if you only get the event name without any context, and except
 
 (processor-formatter)=
 
-### Rendering Using *structlog*-based Formatters Within `logging`
+### Rendering using *structlog*-based formatters within `logging`
 
 Finally, the most ambitious approach.
 Here, you use *structlog*'s {class}`~structlog.stdlib.ProcessorFormatter` as a {any}`logging.Formatter` for both `logging` as well as *structlog* log entries.

docs/thread-local.md

@@ -21,7 +21,7 @@ structlog.reset_defaults()
 ```
 
 
-## The `merge_threadlocal` Processor
+## The `merge_threadlocal` processor
 
 *structlog* provides a simple set of functions that allow explicitly binding certain fields to a global (thread-local) context and merge them later using a processor into the event dict.
 
@@ -43,15 +43,15 @@ These functions map 1:1 to the {doc}`contextvars` APIs, so please use those inst
 - {func}`structlog.contextvars.get_merged_contextvars`
 
 
-## Thread-local Contexts
+## Thread-local contexts
 
 *structlog* also provides thread-local context storage in a form that you may already know from [*Flask*](https://flask.palletsprojects.com/en/latest/design/#thread-locals) and that makes the *entire context* global to your thread or greenlet.
 
 This makes its behavior more difficult to reason about which is why we generally recommend to use the {func}`~structlog.contextvars.merge_contextvars` route.
 Therefore, there are currently no plans to re-implement this behavior on top of context variables.
 
 
-### Wrapped Dicts
+### Wrapped dicts
 
 In order to make your context thread-local, *structlog* ships with a function that can wrap any dict-like class to make it usable for thread-local storage: {func}`structlog.threadlocal.wrap_dict`.
 
@@ -123,7 +123,7 @@ The state before the `with` statement is saved and restored once it's left.
 If you want to detach a logger from thread-local data, there's {func}`structlog.threadlocal.as_immutable`.
 
 
-#### Downsides & Caveats
+#### Downsides & caveats
 
 The convenience of having a thread-local context comes at a price though: