Merge pull request #73 from kraken-tech/meshy/docs/links

Link to docs where we discuss APIs

Author: meshy

docs/transactions-savepoints-and-atomic.md

@@ -16,14 +16,14 @@ and is committed with `COMMIT`.
 A transaction can be ended without committing using `ROLLBACK`.
 
 When using Django Subatomic,
-transactions are created with `django_subatomic.db.transaction`,
+transactions are created with [`transaction`][django_subatomic.db.transaction],
 which can be used as both a decorator and a context manager.
 
 !!! Note
 
     SQL does not support nested transactions,
     so nesting is not supported by `transaction`.
-    It acts like [Django's `atomic` with `durable=True`](https://docs.djangoproject.com/en/5.0/topics/db/transactions/#controlling-transactions-explicitly).
+    It acts like [Django's `atomic` with `durable=True`][django-atomic]
 
     See [_Atomic code_](#atomic-code)
     for code which requires a transaction, but doesn't require partial rollback.
@@ -51,7 +51,7 @@ In SQL terms, a savepoint is created with `SAVEPOINT <name>`.
 It is rolled back with `ROLLBACK TO <name>`
 and discarded with `RELEASE SAVEPOINT <name>`.
 
-Subatomic creates savepoints using `django_subatomic.db.savepoint`.
+Subatomic creates savepoints using [`savepoint`][django_subatomic.db.savepoint].
 This is a context manager,
 and cannot be used as a decorator.
 
@@ -65,23 +65,23 @@ and cannot be used as a decorator.
 Sometimes code needs to make multiple database changes atomically
 in a place that should not be responsible for managing a transactions.
 
-Decorate this code with `@django_subatomic.db.transaction_required`
+Decorate this code with [`@transaction_required`][django_subatomic.db.transaction_required]
 to make it raise an exception when someone tries to run it without first opening a transaction.
 
 !!! Tip
 
-    Where possible, use `transaction_required` as a decorator.
+    Where possible, use [`transaction_required`][django_subatomic.db.transaction_required] as a decorator.
 
     This form is preferred because it fails earlier,
     and presents a clearer requirement to programmers.
 
-    You can still use `transaction_required` as a context manager though.
+    You can still use [`transaction_required`][django_subatomic.db.transaction_required] as a context manager though.
     This might be useful in code where you cannot know the required database
     (such as when the database name is passed in as a function parameter).
 
 !!! Warning
 
-    When testing code which uses `transaction_required`
+    When testing code which uses [`transaction_required`][django_subatomic.db.transaction_required],
     you might see `_MissingRequiredTransaction`
     even though tests are run in a transaction by default.
 
@@ -93,15 +93,15 @@ to make it raise an exception when someone tries to run it without first opening
     then you have probably forgotten to open a transaction.
 
     The trade-off is that lower-level tests will see this error too.
-    If you're testing `transaction_required` code directly,
+    If you're testing [`transaction_required`][django_subatomic.db.transaction_required] code directly,
     and you're _sure_ that the code shouldn't be responsible for opening a transaction,
-    use the `django_subatomic.test.part_of_a_transaction()` decorator/context-manager
+    use the [`part_of_a_transaction`][django_subatomic.test.part_of_a_transaction] decorator/context-manager
     to get things working.
     This will not run after-commit hooks.
     If you'd like those to run, create a [transaction](#transactions) instead.
 
 When "create-a-transaction-if-one-doesn't-already-exist" behaviour is required,
-the `transaction_if_not_already` function will provide it.
+the [`transaction_if_not_already`][django_subatomic.db.transaction_if_not_already] function will provide it.
 This approach hints that transactional behaviour is not well-defined:
 the code will do different things in different contexts,
 which makes it hard to know what to expect from it.

docs/why.md

@@ -1,19 +1,19 @@
 # Django's Atomic
 
-This doc will discuss the behaviours available through Django's `atomic`
+This doc will discuss the behaviours available through [Django's `atomic`][atomic]
 and the outcomes people are usually trying to achieve with it.
-It goes on to outline some pitfalls that can result from using `atomic`
+It goes on to outline some pitfalls that can result from using [`atomic`][atomic]
 and how Subatomic avoids them.
 
-Django's `atomic` ensures database changes are committed together-or-not-at-all.
+Django's [`atomic`][atomic] ensures database changes are committed together-or-not-at-all.
 It creates a savepoint or a transaction depending on two factors:
 
 - The arguments passed to it (`durable=` and `savepoint=`).
 - If a database transaction is already open.
 
 ## Behaviours
 
-The *Behaviours* which `atomic` exhibits are:
+The *Behaviours* which [`atomic`][atomic] exhibits are:
 
 | `savepoint=`         | `durable=False` (default) | `durable=True` |
 | ---                  | ---                       | ---            |
@@ -22,7 +22,7 @@ The *Behaviours* which `atomic` exhibits are:
 
 ## Outcomes
 
-When people use `atomic`,
+When people use [`atomic`][atomic],
 they're generally trying to achieve one of three *Outcomes*:
 
 1. to create a *transaction*
@@ -39,15 +39,16 @@ they're generally trying to achieve one of three *Outcomes*:
 
 Ideally, we should be able to look at a line of code and say what it will do.
 
-Because `atomic`'s behaviour depends on whether a transaction is already open,
+Because [`atomic`][atomic]'s behaviour depends on whether a transaction is already open,
 one must know the full call stack
-to know what any particular `atomic` will do.
+to know what any particular [`atomic`][atomic] will do.
 If it is called in multiple code paths,
 developers must know that it will do different database operations
 depending on who calls it.
 
 Subatomic avoids this issue
-by offering an unambiguous API (`transaction()`, `savepoint()`, etc).
+by offering an unambiguous API
+([`transaction()`][django_subatomic.db.transaction], [`savepoint()`][django_subatomic.db.savepoint], etc).
 
 ### Transactions without context
 
@@ -57,7 +58,7 @@ but cannot know if it is part of a larger suite of changes
 managed by higher-level code
 which must also be committed together.
 
-When low-level code uses `atomic`
+When low-level code uses [`atomic`][atomic]
 to indicate that its changes should be atomic (*Outcome* **3**),
 this can have one of two effects:
 
@@ -75,22 +76,22 @@ the creation of a savepoint (*Outcome* **2**)
 or the need for atomicity (*Outcome* **3**)
 that doesn't have the potential to create a transaction instead.
 
-A function decorated with Subatomic's `@transaction_required`
+A function decorated with Subatomic's [`@transaction_required`][django_subatomic.db.transaction_required]
 will raise an error when called outside of a transaction,
 rather than run the risk of creating a transaction with the wrong scope.
 
 ### Savepoints by default
 
-`atomic` defaults to *Behaviour* **A**
+[`atomic`][atomic] defaults to *Behaviour* **A**
 which creates savepoints by default
 when there is already an open transaction.
 
-It's common to decorate functions with `atomic`
+It's common to decorate functions with [`atomic`][atomic]
 to indicate that code should be atomic (*Outcome* **3**),
 but neglect to pass `savepoint=False`.
 This results in more database queries than necessary.
 
-Subatomic's `@transaction_required` decorator
+Subatomic's [`@transaction_required`][django_subatomic.db.transaction_required] decorator
 gives developers an unambiguous alternative
 that will never open a savepoint.
 
@@ -102,7 +103,7 @@ a safe place to continue from after a failure within a transaction.
 Ideally then, the logic for catching the failure and continuing a transaction
 should be adjacent to the logic which creates the savepoint.
 
-When we use `atomic` as a decorator,
+When we use [`atomic`][atomic] as a decorator,
 we separate the savepoint creation from the error handling logic.
 The decorated function will not be within a `try:...except...:`.
 
@@ -111,25 +112,25 @@ can make it difficult to know
 where continuing after rolling back a savepoint is intended to be handled,
 or even if it is handled at all.
 This is compounded by the fact that
-because `atomic`'s API is ambiguous,
+because [`atomic`][atomic]'s API is ambiguous,
 it can be hard to know the intended *Outcome*.
 
 To encourage putting rollback logic alongside savepoint creation,
-Subatomic's `savepoint` cannot be used as a decorator.
+Subatomic's [`savepoint`][django_subatomic.db.savepoint] cannot be used as a decorator.
 
 ### Tests without after-commit callbacks
 
 To avoid leaking state between tests,
-Django's `TestCase` runs each test within a transaction
+Django's [`TestCase`][TestCase] runs each test within a transaction
 which gets rolled back at the end of the test.
 As a result,
-`atomic` blocks encountered during the test
+[`atomic`][atomic] blocks encountered during the test
 will not create transactions
 so no after-commit callbacks will be run.
 
 Even if Django wanted to simulate after-commit callbacks in tests,
 it has no way to know which *Outcome* was intended
-when it encounters an `atomic` block.
+when it encounters an [`atomic`][atomic] block.
 It might be running a high-level test where a transaction is intended
 and callbacks should be run,
 or a low-level test where an open transaction is assumed
@@ -138,9 +139,13 @@ and callbacks should _not_ be run.
 Without Subatomic,
 developers must either manually run after-commit callbacks in tests,
 which is prone to error and omission,
-or run the test using `TransactionTestCase`,
+or run the test using [`TransactionTestCase`][TransactionTestCase],
 which can be very slow.
 
-Subatomic's `transaction()` function
+Subatomic's [`transaction()`][django_subatomic.db.transaction] function
 will run after-commit callbacks automatically in tests
 so that code behaves the same in tests as it does in production.
+
+[atomic]: https://docs.djangoproject.com/en/stable/topics/db/transactions/#django.db.transaction.atomic
+[TestCase]: https://docs.djangoproject.com/en/stable/topics/testing/tools/#django.test.TestCase
+[TransactionTestCase]: https://docs.djangoproject.com/en/stable/topics/testing/tools/#django.test.TransactionTestCase