Opened 2 years ago

Closed 2 years ago

#6925 enhancement closed fixed (fixed)

Add narrative documentation which demonstrates how to use twisted.names.client module

Reported by: rwall Owned by: rwall
Priority: normal Milestone:
Component: names Keywords: documentation
Cc: Branch: branches/names-client-documentation-6925
(github, coverage, patch, buildbot, log)
Author: rwall

Description

There are three decent twisted.names.client examples, but they don't have any accompanying narrative documentation.

There is also some good documentation on wiki:TwistedNames, which would be better copied or moved to the main docs directory; where it can be rendered using sphinx for specific versions, and with API links etc.

Change History (6)

comment:1 Changed 2 years ago by rwall

  • Author set to rwall
  • Branch set to branches/names-client-documentation-6925

(In [41388]) Branching to 'names-client-documentation-6925'

comment:2 Changed 2 years ago by rwall

  • Keywords review added

Ready for review in log:branches/names-client-documentation-6925

  • Fixed the twisted.names example tests -- which had broken with the change to sphinx
  • Copied most of jerub's content from wiki:TwistedNames and expanded it a bit
  • Added an example of using the DNS protocols directly -- taken from my Twisted Names talk at PyconUK

I'm not sure whether the use of twisted.conch.stdio is neat or distracting.

It might be worth converting those to self contained example scripts instead.

Build Results:

(Although I don't think the documentation build is actually working with sphinx at the moment.)

-RichardW.

comment:3 Changed 2 years ago by hynek

  • Owner set to hynek

comment:4 follow-up: Changed 2 years ago by hynek

  • Keywords review removed
  • Owner changed from hynek to rwall

Thanks again for working on names documentation; that’s like adding it to Twisted at last.

  1. It builds fine.
  2. Big Picture
    1. Since this is the most basic guide, I figure it could/should be first in the list of guides? (docs/projects/names/howto/index.rst)
    2. I’m not the biggest fan of the repetition within the “In this section:” block. How would you feel about:
       In this section you will learn:
      
      * about the high level :api:`twisted.names.client <client>` API,
      * how you can use the client API interactively from the Python shell (useful for DNS debugging and diagnostics),
      * about the :api:`twisted.internet.interfaces.IResolverSimple <IResolverSimple>` and the :api:`twisted.internet.interfaces.IResolver <IResolver>` interfaces,
      * about various implementations of those interfaces and when to use them,
      * how to customise how the reactor carries out hostname resolution,
      * and finally you will also be introduced to some of the low level APIs.
      
      That IMHO gives a better idea what will be learned due to less noise.
    3. I wondered what point this twisted.conch.stdio thing is about but it apparently runs an reactor so that deferreds fire eventually!? That’s great, TIL. :) Maybe explain it a bit better in line 28? The current logic is that “because conch, we get deferred” but it should be “because conch, deferreds fire eventually”. I’m not sure whether you need to write it out both times though.
    4. Re the Note in 105ff: do you really want it to be three paragraphs? I would suggest to make it a bulleted list since it looks like an enumeration. I would also suggest to link gethostbyname; maybe to http://www.freebsd.org/cgi/man.cgi?query=gethostbyname&section=3 ?
  3. Nits
    1. 21: Twisted
    2. 54: POSIX
    3. 69: if you mean generally “resolver” it shouldn’t be capitalized, if you mean some class/interface, it should be Resolver’ed. Since you explicitly mention client.Resolver in the next line, I would suggest the former.
    4. 93: whenever
    5. 106: POSIX

I would like to see the nits and at least 2.3 and 2.4 addressed, otherwise it looks good to me. Feel free to merge after that whenever you feel confident.

comment:5 in reply to: ↑ 4 Changed 2 years ago by rwall

  • Status changed from new to assigned

Thanks for the review Hynek,

I've addressed all your points and will merge shortly.

More details below:

Replying to hynek:

Thanks again for working on names documentation; that’s like adding it to Twisted at last.

  1. It builds fine.
  2. Big Picture
  1. Since this is the most basic guide, I figure it could/should be first in the list of guides? (docs/projects/names/howto/index.rst)

r41427

  1. I’m not the biggest fan of the repetition within the “In this section:” block. How would you feel about:

r41428

  1. I wondered what point this twisted.conch.stdio thing is about but it apparently runs an reactor so that deferreds fire eventually!? That’s great, TIL. :) Maybe explain it a bit better in line 28? The current logic is that “because conch, we get deferred” but it should be “because conch, deferreds fire eventually”. I’m not sure whether you need to write it out both times though.

r41430

  1. Re the Note in 105ff: do you really want it to be three paragraphs? I would suggest to make it a bulleted list since it looks like an enumeration. I would also suggest to link gethostbyname; maybe to http://www.freebsd.org/cgi/man.cgi?query=gethostbyname&section=3 ?

r41431

I linked to the stdlib documentation instead -- which is what t.i.i.IResolverSimple.getHostByName is really equivalent to.

r41437

  1. Nits
    1. 21: Twisted

r41432.

  1. 54: POSIX

r41433

  1. 69: if you mean generally “resolver” it shouldn’t be capitalized, if you mean some class/interface, it should be Resolver’ed. Since you explicitly mention client.Resolver in the next line, I would suggest the former.

r41434

  1. 93: whenever

r41435

  1. 106: POSIX

r41433

Also thread pool. r41436

I would like to see the nits and at least 2.3 and 2.4 addressed, otherwise it looks good to me. Feel free to merge after that whenever you feel confident.

comment:6 Changed 2 years ago by rwall

  • Resolution set to fixed
  • Status changed from assigned to closed

(In [41438]) Merge names-client-documentation-6925

Author: rwall Reviewers: hynek Fixes: #6925

twisted.names now has narrative documentation explaining how to use its client APIs.

Note: See TracTickets for help on using tickets.