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

File lore-core-development-cleanups.diff, 18.5 KB (added by Screwtape, 4 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