Summary
changed from Add narrative documentation showing how to use twisted.names.authority to create a custom authoritative server to Add narrative documentation showing how to use twisted.names to create a custom server

I don't see simple_server.py or override_server.py. Did you forget to check them in, or am I just blind?

Note that in RestructuredText when marking up a literal block (using ::), you can put the :: at the end of the preceding line, similar to how one might use a colon to lead into the block. So instead of:

here's some code
::
code goes here

you'd have something like:

here's some code::
code goes here

I think this makes the markup look a bit nicer, and would recommend changing to this style, but don't block the ticket on this if you disagree.

Maybe I'm being a bit overly-pedantic, but in yoru explanatory note section, you say:

It takes a list of :api:`twisted.internet.interfaces.IResolver <IResolver>` providers and queries each one in turn until it receives an answer.

Perhaps it should be more exact, like:

It takes a list of :api:`twisted.internet.interfaces.IResolver <IResolver>` providers and queries each one in turn until either it receives an answer, or they all fail.

Probably you can make that sentence flow a little better, but I think it should be made clear that it isn't going to repeat the chain over and over. Maybe this change isn't strictly necessary, but I think it makes things a little more clear for those who aren't very familiar with Twisted.

The narrative itself looks pretty good, but it's difficult to say without seeing the actual code examples. Please add the code or point out what I'm missing and resubmit for review.

I don't see simple_server.py or override_server.py. Did you forget to check them in, or am I just blind?

They are there, but may not be shown in the Trac diff because they're new files.
Trac does show the links to those files at the top of the diff page though (in green).

Note that in RestructuredText when marking up a literal block (using ::), you can put the :: at the end of the preceding line, similar to how one might use a colon to lead into the block. So instead of:

Yeah, I had tried that, but I was confused because it renedered as a single : at
the end of the line, or sometimes a :: if there was a preceding full stop.

And neither form resulted in syntax highlighting, so I've switched to the
'.. code-block:: console' syntax instead.

Probably you can make that sentence flow a little better, but I think it should be made clear that it isn't going to repeat the chain over and over. Maybe this change isn't strictly necessary, but I think it makes things a little more clear for those who aren't very familiar with Twisted.

I agree. I've changed it. And added a little more detail about the use of DomainError.

This looks great and could be merged as it is, but here's a couple of things which might improve it:

Some of the lines in the RestructuredText files are pretty long, and should probably be shortened

In the override_server.py example, in DynamicResolver._doDynamicResponse the return values are a bit opaque. I'm not too concerned about this, since it is explained in the narrative text, but you might consider adding each of the three return values to temporary/throwaway variables with appropriate names, and then returning those names, just to help clarify things.