Ticket #4567: lore-core-development-cleanups.diff

File lore-core-development-cleanups.diff, 18.5 KB (added by Screwtape, 6 years ago)

Changes that make the lore2sphinx conversion cleaner.

  • doc/core/development/policy/coding-standard.xhtml

    diff --git a/doc/core/development/policy/coding-standard.xhtml b/doc/core/development/policy/coding-standard.xhtml
    index 1dd4af4..1723970 100644
    a b  
    3636
    3737    <p>Twisted development should always be
    3838     <a href="http://en.wikipedia.org/wiki/Test-driven_development">
    39      test-driven</a>.  The complete test suite in trunk@HEAD is required to
     39     test-driven</a>.  The complete test suite in the head of the SVN trunk is required to
    4040     be passing on <a href="http://buildbot.twistedmatrix.com/supported">
    4141     supported platforms</a> at all times.  Regressions in the test suite
    4242     are addressed by reverting whatever revisions introduced them.  For
     
    5555     the test suite are generally better examples than older parts - check
    5656     when the code you are looking at was written before you use it as an
    5757     example of what you should write).  The names of test modules should
    58      begin with <q>test_</q> so that they are automatically discoverable by
     58     begin with <code>test_</code> so that they are automatically discoverable by
    5959     test runners such as Trial.  Twisted's unit tests are written using
    6060     <code class="API">twisted.trial</code>, an xUnit library which has been
    6161     extensively customized for use in testing Twisted and Twisted-based
    myref.callRemote("addUser", name="bob", phone="555-1212") 
    527527</pre>
    528528
    529529    <p>In this case, <code>callRemote</code> (and any code that uses the
    530     **kwargs syntax) must be careful to not use <q>name</q>, <q>phone</q>, or
    531     any other name that might overlap with a user-provided named parameter.
    532     Therefore, <code>callRemote</code> is implemented with the following
    533     signature:</p>
     530    <code class="python">**kwargs</code> syntax) must be careful to not use
     531    <q>name</q>, <q>phone</q>, or any other name that might overlap with
     532    a user-provided named parameter.  Therefore, <code>callRemote</code> is
     533    implemented with the following signature:</p>
    534534
    535535<pre class="python">
    536536def callRemote(self, _name, *args, **kw):
    def callRemote(self, _name, *args, **kw): 
    545545
    546546    <h2>Special Methods</h2>
    547547
    548     <p>The augmented assignment protocol, defined by __iadd__ and other
     548    <p>The augmented assignment protocol, defined by <code
     549    class="python">__iadd__</code> and other
    549550    similarly named methods, can be used to allow objects to be modified in
    550551    place or to rebind names if an object is immutable -- both through use
    551552    of the same operator.  This can lead to confusing code, which in turn
  • doc/core/development/policy/doc-standard.xhtml

    diff --git a/doc/core/development/policy/doc-standard.xhtml b/doc/core/development/policy/doc-standard.xhtml
    index 68ef7c4..ff0d4ce 100644
    a b  
    1212
    1313    <h2>Allowable Tags</h2>
    1414
    15     <p>Please try to restrict your HTML usage to the following tags (all only for the original logical purpose, and not whatever visual effect you see): <code>&lt;html&gt;</code>, <code>&lt;title&gt;</code>, <code>&lt;head&gt;</code>, <code>&lt;body&gt;</code>, <code>&lt;h1&gt;</code>, <code>&lt;h2</code>, <code>&lt;h3&gt;</code>, <code>&lt;ol&gt;</code>, <code>&lt;ul&gt;</code>, <code>&lt;dl&gt;</code>, <code>&lt;li&gt;</code>,   <code>&lt;dt&gt;</code>, <code>&lt;dd&gt;</code>, <code>&lt;p&gt;</code>, <code>&lt;code&gt;</code>,  <code>&lt;img&gt;</code>,  <code>&lt;blockquote&gt;</code>,  <code>&lt;a&gt;</code>,  <code>&lt;cite&gt;</code>, <code>&lt;div&gt;</code>, <code>&lt;span&gt;</code>, <code>&lt;strong&gt;</code>, <code>&lt;em&gt;</code>, <code>&lt;pre&gt;</code>, <code>&lt;q&gt;</code>, <code>&lt;table&gt;</code>,<code>&lt;tr&gt;</code>, <code>&lt;td&gt;</code> and <code>&lt;th&gt;</code>.</p>
     15    <p>Please try to restrict your HTML usage to the following tags (all only for the original logical purpose, and not whatever visual effect you see): <code>&lt;html&gt;</code>, <code>&lt;title&gt;</code>, <code>&lt;head&gt;</code>, <code>&lt;body&gt;</code>, <code>&lt;h1&gt;</code>, <code>&lt;h2</code>, <code>&lt;h3&gt;</code>, <code>&lt;ol&gt;</code>, <code>&lt;ul&gt;</code>, <code>&lt;dl&gt;</code>, <code>&lt;li&gt;</code>,   <code>&lt;dt&gt;</code>, <code>&lt;dd&gt;</code>, <code>&lt;p&gt;</code>, <code>&lt;code&gt;</code>,  <code>&lt;img&gt;</code>,  <code>&lt;blockquote&gt;</code>,  <code>&lt;a&gt;</code>,  <code>&lt;cite&gt;</code>, <code>&lt;div&gt;</code>, <code>&lt;span&gt;</code>, <code>&lt;strong&gt;</code>, <code>&lt;em&gt;</code>, <code>&lt;pre&gt;</code>, <code>&lt;q&gt;</code>, <code>&lt;table&gt;</code>, <code>&lt;tr&gt;</code>, <code>&lt;td&gt;</code> and <code>&lt;th&gt;</code>.</p>
    1616
    1717    <p>Please avoid using the quote sign (<code>"</code>) for quoting, and use the relevant html tags (<code>&lt;q&gt;&lt;/q&gt;</code>) -- it is impossible to distinguish right and left quotes with the quote sign, and some more sophisticated output methods work better with that distinction.</p>
    1818
     
    2424    and <q>shell</q>. For example:</p>
    2525
    2626    <h3><q>python</q></h3>
     27    <p>Original markup:</p>
     28    <blockquote>
    2729<pre>
    28     &lt;p&gt;
    29     For example, this is how one defines a Resource:
    30     &lt;/p&gt;
     30&lt;p&gt;
     31For example, this is how one defines a Resource:
     32&lt;/p&gt;
    3133
    32     &lt;pre class="python"&gt;
     34&lt;pre class="python"&gt;
    3335from twisted.web import resource
    3436
    3537class MyResource(resource.Resource):
    3638    def render_GET(self, request):
    3739        return "Hello, world!"
    38     &lt;/pre&gt;
     40&lt;/pre&gt;
    3941</pre>
     42    </blockquote>
    4043
     44    <p>Rendered result:</p>
     45    <blockquote>
    4146    <p>For example, this is how one defines a Resource:</p>
    4247<pre class="python">
    4348from twisted.web import resource
    class MyResource(resource.Resource): 
    4752        return "Hello, world!"
    4853   
    4954</pre>
     55    </blockquote>
    5056
    5157    <p>Note that you should never have leading indentation inside a
    5258    &lt;pre&gt; block -- this makes it hard for readers to
    5359    copy/paste the code.</p>
    5460
    5561    <h3><q>python-interpreter</q></h3>
     62    <p>Original markup:</p>
     63    <blockquote>
    5664<pre>
    57     &lt;pre class="python-interpreter"&gt;
    58     &amp;gt;&amp;gt;&amp;gt; from twisted.web import resource
    59     &amp;gt;&amp;gt;&amp;gt; class MyResource(resource.Resource):
    60     ...     def render_GET(self, request):
    61     ...         return "Hello, world!"
    62     ...
    63     &amp;gt;&amp;gt;&amp;gt; MyResource().render_GET(None)
    64     "Hello, world!"
    65     &lt;/pre&gt;
     65&lt;pre class="python-interpreter"&gt;
     66&amp;gt;&amp;gt;&amp;gt; from twisted.web import resource
     67&amp;gt;&amp;gt;&amp;gt; class MyResource(resource.Resource):
     68...     def render_GET(self, request):
     69...         return "Hello, world!"
     70...
     71&amp;gt;&amp;gt;&amp;gt; MyResource().render_GET(None)
     72"Hello, world!"
     73&lt;/pre&gt;
    6674</pre>
     75    </blockquote>
    6776
     77    <p>Rendered result:</p>
     78    <blockquote>
    6879<pre class="python-interpreter">
    6980&gt;&gt;&gt; from twisted.web import resource
    7081&gt;&gt;&gt; class MyResource(resource.Resource):
    class MyResource(resource.Resource): 
    7485&gt;&gt;&gt; MyResource().render_GET(None)
    7586"Hello, world!"
    7687</pre>
     88    </blockquote>
    7789
    7890    <h3><q>shell</q></h3>
     91    <p>Original markup:</p>
     92    <blockquote>
    7993<pre>
    8094    &lt;pre class="shell"&gt;
    8195    $ twistd web --path /var/www
    8296    &lt;/pre&gt;
    8397</pre>
     98    </blockquote>
    8499
     100    <p>Rendered result:</p>
     101    <blockquote>
    85102<pre class="shell">
    86103$ twistd web --path /var/www
    87104</pre>
     105    </blockquote>
    88106
    89107    <h2>Code inside paragraph text</h2>
    90108
    $ twistd web --path /var/www 
    103121    to the module or classname.  This is to help keep the documentation
    104122    clearer and less cluttered by allowing links to API docs that don't
    105123    need the module name.</p>
     124    <p>Original markup:</p>
     125    <blockquote>
    106126<pre>
    107127        &lt;p&gt;
    108128    To add a &lt;code class="API"&gt;twisted.web.widgets.Widget&lt;/code&gt;
    $ twistd web --path /var/www 
    120140        &lt;/p&gt;
    121141   
    122142</pre>
     143    </blockquote>
    123144
    124 <div class="boxed">
     145    <p>Rendered result:</p>
     146    <blockquote>
    125147        <p>
    126148    To add a <code class="API">twisted.web.widgets.Widget</code>
    127149    instance to a <code class="API" base="twisted.web.widgets">Gadget</code>
    $ twistd web --path /var/www 
    135157    which is a
    136158    list.)
    137159        </p>
    138 
    139 </div>
     160    </blockquote>
    140161
    141162    <h2>Headers</h2>
    142163
  • doc/core/development/policy/svn-dev.xhtml

    diff --git a/doc/core/development/policy/svn-dev.xhtml b/doc/core/development/policy/svn-dev.xhtml
    index ae4ea97..0ee68f9 100644
    a b edge.</p> 
    2222
    2323<h2>Checkout</h2>
    2424
    25 <p>Subversion tutorials can be found elsewhere, see in particular
     25<p>Subversion tutorials can be found elsewhere, see in particular 
    2626<a href="http://subversion.apache.org/">the Subversion homepage</a>. The
    2727relevant data you need to check out a copy of the Twisted tree is available on
    28 the <a href="http://twistedmatrix.com/trac/wiki/TwistedDevelopment">development
     28the <a href="http://twistedmatrix.com/trac/wiki/TwistedDevelopment">development 
    2929page</a>, and is as follows:</p>
    3030
    3131<pre class="shell">
    $ svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk Twisted 
    3535<h2>Alternate tree names</h2>
    3636
    3737<p>By using <code>svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk
    38 otherdir</code>, you can put the workspace tree in a directory other than
     38otherdir</code>, you can put the workspace tree in a directory other than 
    3939<q>Twisted</q>. I do this (with a name like <q>Twisted-Subversion</q>) to
    4040remind myself that this tree comes from Subversion and not from a released
    4141version (like <q>Twisted-1.0.5</q>). This practice can cause a few problems,
    4242because there are a few places in the Twisted tree that need to know where
    4343the tree starts, so they can add it to <code>sys.path</code> without
    4444requiring the user manually set their PYTHONPATH. These functions walk the
    45 current directory up to the root, looking for a directory named
    46 <q>Twisted</q> (sometimes exactly that, sometimes with a
     45current directory up to the root, looking for a directory named 
     46<q>Twisted</q> (sometimes exactly that, sometimes with a 
    4747<code>.startswith</code> test). Generally these are test scripts or other
    4848administrative tools which expect to be launched from somewhere inside the
    4949tree (but not necessarily from the top).</p>
    problems.</p> 
    5858
    5959<h2>Combinator</h2>
    6060
    61 <p>In order to simplify the use of Subversion, we typically use
     61<p>In order to simplify the use of Subversion, we typically use 
    6262<a href="http://divmod.org/trac/wiki/DivmodCombinator">Divmod Combinator</a>.
    6363You may find it to be useful, too.  In particular, because Twisted uses
    6464branches for almost all feature development, if you plan to contribute to
    6565Twisted you will probably find Combinator very useful.  For more details,
    66 see the Combinator website, as well as the
     66see the Combinator website, as well as the 
    6767<a href="http://divmod.org/trac/wiki/UltimateQualityDevelopmentSystem">
    6868UQDS</a> page.</p>
    6969
    7070<h2>Compiling C extensions</h2>
    7171
    7272<p>
    73 There are currently several C extension modules in Twisted:
    74 twisted.protocols._c_urlarg, twisted.internet.cfsupport,
    75 twisted.internet.iocpreactor._iocp, and twisted.python._epoll.  These modules
     73There are currently several C extension modules in Twisted:
     74<code class="python">twisted.protocols._c_urlarg</code>,
     75<code class="python">twisted.internet.cfsupport</code>,
     76<code class="python">twisted.internet.iocpreactor._iocp</code>,
     77and <code class="python">twisted.python._epoll</code>.  These modules
    7678are optional, but you'll have to compile them if you want to experience their
    7779features, performance improvements, or bugs. There are two approaches.
    7880</p>
    7981
    8082<p>The first is to do a regular distutils <code>./setup.py build</code>, which
    81 will create a directory under <code>build/</code> to hold both the generated
     83will create a directory under <code>build/</code> to hold both the generated 
    8284<code>.so</code> files as well as a copy of the 600-odd <code>.py</code> files
    8385that make up Twisted. If you do this, you will need to set your PYTHONPATH to
    8486something like <code>MyDir/Twisted/build/lib.linux-i686-2.5</code> in order to
    85 run code against the Subversion twisted (as opposed to whatever's installed in
     87run code against the Subversion twisted (as opposed to whatever's installed in 
    8688<code>/usr/lib/python2.5</code> or wherever python usually looks). In
    8789addition, you will need to re-run the <code>build</code> command <em>every
    8890time</em> you change a <code>.py</code> file. The <code>build/lib.foo</code>
    PYTHONPATH at the top of the tree, like <code>MyDir/Twisted</code>. This way 
    9597you're using the .py files in place too, removing the confusion a forgotten
    9698rebuild could cause with the separate build/ directory above. To build the C
    9799modules in place, do <code>./setup.py build_ext -i</code>. You only need to
    98 re-run this command when you change the C files. Note that
     100re-run this command when you change the C files. Note that 
    99101<code>setup.py</code> is not Make, it does not always get the dependencies
    100102right (<code>.h</code> files in particular), so if you are hacking on the
    101103cReactor you may need to manually delete the <code>.o</code> files before
    do one of:</p> 
    127129<p>This depends upon the <code>.py</code> file having an appropriate
    128130<q>test-case-name</q> tag that indicates which test cases provide coverage.
    129131See the <a href="test-standard.xhtml">Test Standards</a> document for
    130 details about using <q>test-case-name</q>. In this example, the
     132details about using <q>test-case-name</q>. In this example, the 
    131133<code>twisted.mail.test.test_imap</code> test will be run.</p>
    132134
    133135<p>Many tests create temporary files in /tmp or ./_trial_temp, but
    134136everything in /tmp should be deleted when the test finishes. Sometimes these
    135 cleanup calls are commented out by mistake, so if you see a stray
    136 /tmp/@12345.1 directory, it is probably from test_dirdbm or test_popsicle.
     137cleanup calls are commented out by mistake, so if you see a stray 
     138<code>/tmp/@12345.1</code> directory, it is probably from <code>test_dirdbm</code> or <code>test_popsicle</code>.
    137139Look for an <code>rmtree</code> that has been commented out and complain to
    138140the last developer who touched that file.</p>
    139141
    the index file will be placed in <code>doc/howto/index.html</code>.</p> 
    154156./bin/lore/lore -p --config template=doc/howto/template.tpl doc/howto/*.xhtml
    155157</pre>
    156158
    157 <p>To run hlint over a single Lore document, such as
     159<p>To run hlint over a single Lore document, such as 
    158160<code>doc/development/policy/svn-dev.xhtml</code>, do the following. This is
    159161useful because the HTML conversion may bail without a useful explanation if
    160162it sees mismatched tags.</p>
    it sees mismatched tags.</p> 
    164166</pre>
    165167
    166168<p>To convert it to HTML (including markup, interpolation of examples,
    167 footnote processing, etc), do the following. The results will be placed in
     169footnote processing, etc), do the following. The results will be placed in 
    168170<code>doc/development/policy/svn-dev.html</code>:</p>
    169171
    170172<pre class="shell">
    footnote processing, etc), do the following. The results will be placed in 
    176178include a <q>-l</q> argument to <code>bin/lore/lore</code>. Links in the
    177179.xhtml file are to .xhtml targets: when the .xhtml is turned into .html, the
    178180link targets are supposed to be turned into .html also. In addition to this,
    179 Lore markup of the form &lt;code class=&quot;API&quot;&gt; is supposed to
     181Lore markup of the form <code>&lt;code class=&quot;API&quot;&gt;</code> is supposed to
    180182turn into a link to the corresponding API reference page. These links will
    181183probably be wrong unless the correct base URL is provided to Lore.</p>
    182184
    183185<h2>Committing and Post-commit Hooks</h2>
    184186
    185 <p>Twisted uses a customized
     187<p>Twisted uses a customized 
    186188<a href="http://bazaar.launchpad.net/~exarkun/twisted-trac-integration/trunk/annotate/head%3A/trac-hooks/trac-post-commit-hook">
    187189trac-post-commit-hook</a> to enable ticket updates based on svn commit
    188190logs. When making a branch for a ticket, the branch name should end
    Fixes: #9999 
    205207My longer description of the changes made.
    206208</pre>
    207209
    208 <p>The <a href="coding-standard.xhtml#commits">Twisted Coding Standard</a>
     210<p>The <a href="coding-standard.xhtml">Twisted Coding Standard</a>
    209211elaborates on commit messages and source control.</p>
    210212
    211213<h2>Emacs</h2>
    212214
    213 <p>A minor mode for development with Twisted using Emacs is available.  See
     215<p>A minor mode for development with Twisted using Emacs is available.  See 
    214216<code>emacs/twisted-dev.el</code> for several utility functions which make
    215217it easier to grep for methods, run test cases, etc.</p>
    216218
    it easier to grep for methods, run test cases, etc.</p> 
    218220
    219221<p>Our support for building Debian packages has fallen into disrepair.  We
    220222would very much like to restore this functionality, but until we do so, if
    221 you are interested in this, you are on your own.  See
     223you are interested in this, you are on your own.  See 
    222224<a href="http://github.com/astraw/stdeb">stdeb</a> for one possible approach to
    223225this.</p>
    224226
  • doc/core/development/policy/test-standard.xhtml

    diff --git a/doc/core/development/policy/test-standard.xhtml b/doc/core/development/policy/test-standard.xhtml
    index 8df03f6..e1efdfa 100644
    a b operating systems. The important common factor is that nobody considers 
    129129these limitations to be a bug.</p>
    130130
    131131<p>To make it easy to test as much as possible, some tests may be skipped in
    132 certain situations. Individual test cases can raise the
     132certain situations. Individual test cases can raise the 
    133133<code>SkipTest</code> exception to indicate that they should be skipped, and
    134134the remainder of the test is not run. In the summary (the very last thing
    135135printed, at the bottom of the test output) the test is counted as a
    in the issue tracker would be more useful.</p> 
    253253
    254254<p>Trial provides line coverage information, which is very useful to ensure
    255255old code has decent coverage. Passing the <code>--coverage</code> option to
    256 to Trial will generate the coverage information in a file called
     256to Trial will generate the coverage information in a file called 
    257257<code>coverage</code> which can be found in the <code>_trial_temp</code>
    258258folder. This option requires Python 2.3.3 or newer.</p>
    259259
    run the right tests.</p> 
    310310
    311311      <li><a href=
    312312      "http://docs.python.org/library/unittest.html"
    313       ><code>unittest</code></a> module documentation, in the <a href=
     313      >unittest</a> module documentation, in the <a href=
    314314      "http://docs.python.org/library">Python Library
    315315      Reference</a>.</li>
    316316