Merge remote-tracking branch 'atlas/master' into indexing

Author: hjwp

appendix_csvs.asciidoc

@@ -3,7 +3,7 @@
 == Swapping Out the Infrastructure: pass:[<span class="keep-together">Do Everything with CSVs</span>]
 
 This appendix is intended as a little illustration of the benefits of the
-Repository, Unit of Work, and Service Layer patterns. It's intended to
+Repository, Unit of Work, and Service Layer patterns.((("CSVs, doing everyting with", id="ix_CSV"))) It's intended to
 follow from <<chapter_06_uow>>.
 
 Just as we finish building out our Flask API and getting it ready for release,
@@ -178,7 +178,7 @@ with CSVs underlying them instead of a database. And as you'll see, it really is
 === Implementing a Repository and Unit of Work for CSVs
 
 
-Here's what a CSV-based repository could look like.  It abstracts away all the
+Here's what a CSV-based repository could look like.((("repositories", "CSV-based repository")))  It abstracts away all the
 logic for reading CSVs from disk, including the fact that it has to read _two
 different CSVs_, one for batches and one for allocations, and it just gives us
 the familiar `.list()` API, which gives us the illusion of an in-memory
@@ -235,7 +235,7 @@ class CsvRepository(repository.AbstractRepository):
 // TODO (hynek) re self._load(): DUDE! no i/o in init!
 
 
-And here's what a UoW for CSVs would look like:
+And here's((("Unit of Work pattern", "UoW for CSVs"))) what a UoW for CSVs would look like:
 
 
 
@@ -289,7 +289,7 @@ def main(folder):
 ====
 
 
-Ta-da! _Now are y'all impressed or what_?
+Ta-da! _Now are y'all impressed or what_?((("CSVs, doing everyting with", startref="ix_CSV")))
 
 Much love,
 

appendix_django.asciidoc

@@ -3,9 +3,9 @@
 == Repository and Unit of Work pass:[<span class="keep-together">Patterns with Django</span>]
 
 Suppose you wanted to use Django instead of SQLAlchemy and Flask. How
-might things look?
+might things look?((("Django", id="ix_Django")))
 
-The first thing is to choose where to install it. We put it in a separate
+The first thing is to choose where to install it.((("Django", "installing"))) We put it in a separate
 package next to our main allocation code:
 
 
@@ -64,7 +64,7 @@ git checkout appendix_django
 
 We used a plug in called
 https://github.com/pytest-dev/pytest-django[`pytest-django`] to help with test
-database management.
+database management.((("Repository pattern", "with Django", id="ix_RepoDjango")))((("Django", "Repository pattern with", id="ix_DjangoRepo")))
 
 Rewriting the first repository test was a minimal change, just rewriting
 some raw SQL with a call to the Django ORM/QuerySet language:
@@ -160,7 +160,7 @@ help minimize boilerplate for this sort of thing.]
 
 ==== Custom Methods on Django ORM Classes to Translate to/from Our Domain Model
 
-Those custom methods look something like this:
+Those custom methods ((("object-relational mappers (ORMs)", "Django, custom methods to translate to/from domain model")))((("domain model", "Django custom ORM methods for conversion")))look something like this:
 
 [[django_models]]
 .Django ORM with custom methods for domain model conversion (src/djangoproject/alloc/models.py)
@@ -220,14 +220,14 @@ class OrderLine(models.Model):
 
 
 NOTE: As in <<chapter_02_repository>>, we use dependency inversion.
-    The ORM (Django) depends on the model, and not the other way around.
+    The ORM (Django) depends on the model, and not the other way around.((("Repository pattern", "with Django", startref="ix_RepoDjango")))((("Django", "Repository pattern with", startref="ix_DjangoRepo")))
 
 
 
 === Unit of Work Pattern with Django
 
 
-The tests don't change too much:
+The tests((("Unit of Work pattern", "with Django", id="ix_UoWDjango")))((("Django", "Unit of Work pattern with", id="ix_DjangoUoW"))) don't change too much:
 
 [[test_uow_django]]
 .Adapted UoW tests (tests/integration/test_uow.py)
@@ -318,13 +318,13 @@ class DjangoUnitOfWork(AbstractUnitOfWork):
     instrumenting the domain model instances themselves, the
     `commit()` command needs to explicitly go through all the
     objects that have been touched by every repository and manually
-    update them back to the ORM.
+    update them back to the ORM.((("Unit of Work pattern", "with Django", startref="ix_UoWDjango")))((("Django", "Unit of Work pattern with", startref="ix_DjangoUoW")))
 
 
 
 === API: Django Views Are Adapters
 
-The Django _views.py_ file ends up being almost identical to the
+The Django _views.py_ file ends ((("views", "Django views as adapters")))((("adapters", "Django views")))((("Django", "views are adapters")))((("APIs", "Django views as adapters")))up being almost identical to the
 old _flask_app.py_, because our architecture means it's a very
 thin wrapper around our service layer (which didn't change at all, by the way):
 
@@ -370,7 +370,7 @@ def allocate(request):
 === Why Was This All So Hard?
 
 OK, it works, but it does feel like more effort than Flask/SQLAlchemy. Why is
-that?
+that?((("Django", "using, difficulty of")))
 
 The main reason at a low level is because Django's ORM doesn't work in the same
 way.  We don't have an equivalent of the SQLAlchemy classical mapper, so our
@@ -397,7 +397,7 @@ around the workflow of state changes.  The Django admin bypasses all of that.
 === What to Do If You Already Have Django
 
 So what should you do if you want to apply some of the patterns in this book
-to a Django app? We'd say the following:
+to a Django app?((("Django", "applying patterns to Django app"))) We'd say the following:
 
 * The Repository and Unit of Work patterns are going to be quite a lot of work. The
   main thing they will buy you in the short term is faster unit tests, so
@@ -430,7 +430,7 @@ your _models.py_, which you can then keep as minimal as possible.
 Suppose you're working on a Django project that you're not sure is going
 to get complex enough to warrant the patterns we recommend, but you still
 want to put a few steps in place to make your life easier, both in the medium
-term, and if you want to migrate to some of our patterns later. Consider the following:
+term, and if you want to migrate to some of our patterns later.((("Django", "applying patterns to Django app", "steps along the way"))) Consider the following:
 
 * One piece of advice we've heard is to put a __logic.py__ into every Django app,
   from day one. This gives you a place to put business logic, and to keep your
@@ -454,5 +454,5 @@ NOTE: We'd like to give a shout out to David Seddon and Ashia Zawaduk for
     stop us from saying anything really stupid about a topic we don't really
     have enough personal experience of, but they may have failed.
 
-For more thoughts and actual lived experience dealing with existing
+For more ((("Django", startref="ix_Django")))thoughts and actual lived experience dealing with existing
 applications, refer to the <<epilogue_1_how_to_get_there_from_here>>.

appendix_ds1_table.asciidoc

@@ -2,7 +2,7 @@
 [appendix]
 == Summary Diagram and Table
 
-Here's what our architecture looks like by the end of the book:
+Here's what our architecture looks((("architecture, summary diagram and table", id="ix_archsumm"))) like by the end of the book:
 
 [[recap_diagram]]
 image::images/apwp_aa01.png["diagram showing all components: flask+eventconsumer, service layer, adapters, domain etc"]
@@ -53,6 +53,6 @@ __Translate external inputs into calls into the service layer.__
 | Web | Receives web requests and translates them into Commands, passing them to the Internal Message Bus.
 | Event consumer | Reads events from the external message bus and translates them into commands, passing them to the internal message bus.
 
-| N/A | External message bus (message broker) | A piece of infrastructure that different services use to intercommunicate, via events.
+| N/A | External message bus (message broker) | A piece of infrastructure that different services use to intercommunicate, via events.((("architecture, summary diagram and table", startref="ix_archsumm")))
 |===
 

appendix_project_structure.asciidoc

@@ -4,7 +4,7 @@
 
 Around <<chapter_04_service_layer>>, we moved from just having
 everything in one folder to a more structured tree, and we thought it might
-be of interest to outline the moving parts.
+be of interest to outline the moving parts.((("projects", "template project structure", id="ix_prjstrct")))
 
 [TIP]
 ====
@@ -354,7 +354,7 @@ TIP: One thing to note is that we install things in the order of how frequently
 
 === Tests
 
-Our tests are kept alongside everything else, as shown here:
+Our tests ((("testing", "tests folder tree")))are kept alongside everything else, as shown here:
 
 [[tests_folder]]
 .Tests folder tree
@@ -396,4 +396,4 @@ These are our basic building blocks:
 * A Makefile for useful command-line, um, commands
 
 We doubt that anyone will end up with _exactly_ the same solutions we did, but we hope you
-find some inspiration here.
+find some inspiration here.((("projects", "template project structure", startref="ix_prjstrct")))

appendix_validation.asciidoc

@@ -2,7 +2,7 @@
 [appendix]
 == Validation
 
-Whenever we're teaching and talking about these techniques, one question that
+Whenever we're ((("validation", id="ix_valid")))teaching and talking about these techniques, one question that
 comes up over and over is "Where should I do validation? Does that belong with
 my business logic, in the domain model, or is that an infrastructural concern?"
 
@@ -514,5 +514,5 @@ Locate each of the three types of validation in the right place::
 TIP: Once you've validated the syntax and semantics of your commands
     at the edges of your system, the domain is the place for the rest
     of your validation.  Validation of pragmatics is often a core part
-    of your business rules.
+    of your business rules.((("validation", startref="ix_valid")))