Commits

Anonymous committed e8bc943

flesh out the README generation process

Comments (0)

Files changed (4)

    <!--
 This HTML is auto-generated from an M-file.
 To make changes, update the M-file and republish this document.
-      --><title>README</title><meta name="generator" content="MATLAB 7.9"><meta name="date" content="2010-07-19"><meta name="m-file" content="README"><style type="text/css">
+      --><title>README</title><meta name="generator" content="MATLAB 7.9"><meta name="date" content="2010-07-20"><meta name="m-file" content="README"><style type="text/css">
 
 body {
   background-color: white;
 not ok 1 - "3 + 3"
     expected: ans = 5
     got     : ans = 6
-</pre><h2>Defining your expectations<a name="3"></a></h2><p>Each time doctest runs a test, it's running a line of code and checking that the output is what you say it should be.  It knows something is an example because it's a line in help('your_function') that starts with '&gt;&gt;'.  It knows what you think the output should be by starting on the line after &gt;&gt; and looking for the next &gt;&gt;, two blank lines, or the end of the documentation.</p><p>If the output of some function will change each time you call it, for instance if it includes a random number or a stack trace, you can put <b>*</b> (three asterisks) where the changing element should be.  This acts as a wildcard, and will match anything.  See the example below.</p><p>Here are some examples of formatting, both ones that work and ones that don't.</p><pre class="codeinput">type <span class="string">formatting</span>
+</pre><h2>Defining your expectations<a name="3"></a></h2><p>Each time doctest runs a test, it's running a line of code and checking that the output is what you say it should be.  It knows something is an example because it's a line in help('your_function') that starts with '&gt;&gt;'.  It knows what you think the output should be by starting on the line after &gt;&gt; and looking for the next &gt;&gt;, two blank lines, or the end of the documentation.</p><p>If the output of some function will change each time you call it, for instance if it includes a random number or a stack trace, you can put '***' (three asterisks) where the changing element should be.  This acts as a wildcard, and will match anything.  See the example below.</p><p>Here are some examples of formatting, both ones that work and ones that don't.</p><pre class="codeinput">type <span class="string">formatting</span>
 disp <span class="string">-------------</span>
 doctest(<span class="string">'formatting'</span>, <span class="string">'CreateLinks'</span>, 0)
 </pre><pre class="codeoutput">
     got     : ans = 5
 not ok 7 - "dicomuid       % FAILS: no wildcard on changing output"
     expected: ans = 1.3.6.1.4.1.9590.100.1.1.944807727511025110.343357080818013
-    got     : ans = 1.3.6.1.4.1.9590.100.1.1.944807727511025110.343387152070056
+    got     : ans = 1.3.6.1.4.1.9590.100.1.1.944807727511025110.343394619430064
 ok 8 - "dicomuid       % passes"
 </pre><h2>Expecting an error<a name="4"></a></h2><p>doctest can deal with errors, a little bit.  You might want this to test that your function correctly detects that it is being given invalid parameters.  But if your example will emit other output BEFORE the error message, the current version can't deal with that.  For more info see Issue #4 on the bitbucket site (below).  Warnings are different from errors, and they work fine.</p><pre class="codeinput">type <span class="string">errors</span>
 disp <span class="string">-------------</span>
 % the documentation.
 %
 % If the output of some function will change each time you call it, for
-% instance if it includes a random number or a stack trace, you can put ***
-% (three asterisks) where the changing element should be.  This acts as a
-% wildcard, and will match anything.  See the example below.
+% instance if it includes a random number or a stack trace, you can put
+% '***' (three asterisks) where the changing element should be.  This acts
+% as a wildcard, and will match anything.  See the example below.
 %
 % Here are some examples of formatting, both ones that work and ones that
 % don't.
 
 Each time doctest runs a test, it's running a line of code and checking that the output is what you say it should be. It knows something is an example because it's a line in help('your_function') that starts with '>>'. It knows what you think the output should be by starting on the line after >> and looking for the next >>, two blank lines, or the end of the documentation.
 
-If the output of some function will change each time you call it, for instance if it includes a random number or a stack trace, you can put ***** (three asterisks) where the changing element should be. This acts as a wildcard, and will match anything. See the example below.
+If the output of some function will change each time you call it, for instance if it includes a random number or a stack trace, you can put '***' (three asterisks) where the changing element should be. This acts as a wildcard, and will match anything. See the example below.
 
 Here are some examples of formatting, both ones that work and ones that don't.
     
         got     : ans = 5
     not ok 7 - "dicomuid       % FAILS: no wildcard on changing output"
         expected: ans = 1.3.6.1.4.1.9590.100.1.1.944807727511025110.343357080818013
-        got     : ans = 1.3.6.1.4.1.9590.100.1.1.944807727511025110.343387152070056
+        got     : ans = 1.3.6.1.4.1.9590.100.1.1.944807727511025110.343394619430064
     ok 8 - "dicomuid       % passes"
     
 
 % the documentation.
 %
 % If the output of some function will change each time you call it, for
-% instance if it includes a random number or a stack trace, you can put ***
-% (three asterisks) where the changing element should be.  This acts as a
-% wildcard, and will match anything.  See the example below.
+% instance if it includes a random number or a stack trace, you can put
+% '***' (three asterisks) where the changing element should be.  This acts
+% as a wildcard, and will match anything.  See the example below.
 %
 % Here are some examples of formatting, both ones that work and ones that
 % don't.
 % comparison, so right now doctest can't detect a failure that's purely a
 % whitespace difference.
 %
-% It can't run lines that are longer than one line of code (so, for
+% It can't run examples that are longer than one line of code (so, for
 % example, no loops that take more than one line).  This is difficult
 % because I haven't found a good way to mark these subsequent lines as
-% part-of-the-source-code rather than part-of-the-result.
+% part-of-the-source-code rather than part-of-the-result.  However,
+% variables that you define in one line do carry over to the next.
 %
 % I haven't found a good way of isolating the variables that you define in
 % the tests from the variables used to run the test.  So, don't run CLEAR
 % To generate .../doctest/README.html, 
 % change directory to .../doctest/doc
 % then run gen_readme
+% 
+% Then in the shell run html2markdown.py README.html > README.markdown
+%
 
 opts = [];
 opts.format = 'html';
 opts.outputDir = '..';
 
 publish('README', opts);
+
+if ~ exist('html2text.py', 'file')
+    ! wget http://www.aaronsw.com/2002/html2text/html2text.py
+    ! chmod a+rx html2text.py
+end
+
+! ./html2text.py ../README.html > ../README.markdown
+
+