Link to our API docs when we discuss our API

Author: meshy

docs/transactions-savepoints-and-atomic.md

@@ -16,7 +16,7 @@ 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
@@ -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

@@ -47,7 +47,8 @@ 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
 
@@ -75,7 +76,7 @@ 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.
 
@@ -90,7 +91,7 @@ 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.
 
@@ -115,7 +116,7 @@ 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
 
@@ -141,7 +142,7 @@ which is prone to error and omission,
 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.