From efbe398a9e374ea4e00391cf3c8b9fc365f5e9eb Mon Sep 17 00:00:00 2001 From: Travis Oliphant Date: Fri, 28 Dec 2007 07:29:22 +0000 Subject: Improve the documentation style for human-readability in plain-text --- numpy/doc/html/epydoc.css | 7 ++ numpy/doc/html/epydoc.js | 17 ++- numpy/doc/html/example-module.html | 140 +++++++++++------------ numpy/doc/html/example-pysrc.html | 202 ++++++++++++++++----------------- numpy/doc/html/help.html | 8 +- numpy/doc/html/identifier-index.html | 8 +- numpy/doc/html/module-tree.html | 8 +- numpy/doc/html/toc-everything.html | 3 +- numpy/doc/html/toc-example-module.html | 3 +- numpy/doc/html/toc.html | 3 +- 10 files changed, 206 insertions(+), 193 deletions(-) (limited to 'numpy/doc/html') diff --git a/numpy/doc/html/epydoc.css b/numpy/doc/html/epydoc.css index 4bb3e0b68..86d417068 100644 --- a/numpy/doc/html/epydoc.css +++ b/numpy/doc/html/epydoc.css @@ -28,6 +28,8 @@ h2 { font-size: +125%; font-style: italic; h3 { font-size: +110%; font-style: italic; font-weight: normal; } code { font-size: 100%; } +/* N.B.: class, not pseudoclass */ +a.link { font-family: monospace; } /* Page Header & Footer * - The standard page header consists of a navigation bar (with @@ -158,6 +160,11 @@ table.summary a.summary-sig-name:visited .summary-sig-arg { color: #006040; } .summary-sig-default { color: #501800; } +/* Subclass list + */ +ul.subclass-list { display: inline; } +ul.subclass-list li { display: inline; } + /* To render variables, classes etc. like functions */ table.summary .summary-name { color: #006080; font-weight: bold; font-family: monospace; } diff --git a/numpy/doc/html/epydoc.js b/numpy/doc/html/epydoc.js index b5b2ddc40..e787dbcf4 100644 --- a/numpy/doc/html/epydoc.js +++ b/numpy/doc/html/epydoc.js @@ -17,8 +17,11 @@ function toggle_private() { if (elts[i].className == "private") { elts[i].style.display = ((cmd && cmd.substr(0,4)=="hide")?"none":"block"); } + else if (elts[i].className == "public") { + elts[i].style.display = ((cmd && cmd.substr(0,4)=="hide")?"block":"none"); + } } - // Update all table rowss containing private objects. Note, we + // Update all table rows containing private objects. Note, we // use "" instead of "block" becaue IE & firefox disagree on what // this should be (block vs table-row), and "" just gives the // default for both browsers. @@ -33,7 +36,7 @@ function toggle_private() { for(var i=0; iModule example

source code

This is the docstring for the example.py module. Modules names should -have short, all-lowercase names. The module name may have underscores if -this improves readability.

-

Every module should have a docstring at the very top of the file. The -module's docstring may extend over multiple lines. If your docstring does -extend over multiple lines, the closing three quotation marks must be on -a line by itself, preferably preceeded by a blank line.

+ have short, all-lowercase names. The module name may have underscores if + this improves readability.

+

Every module should have a docstring at the very top of the file. The + module's docstring may extend over multiple lines. If your docstring + does extend over multiple lines, the closing three quotation marks must + be on a line by itself, preferably preceeded by a blank line.

@@ -166,63 +166,63 @@ a line by itself, preferably preceeded by a blank line.

source code  - + -

One-line summary or signature.

-

Several sentences providing an extended description. You can put -text in mono-spaced type like so: var.

-

Parameters:

-
-
-
var1 : {array_like}
-
Array_like means all those objects -- lists, nested lists, etc. -- -that can be converted to an array.
-
var2 : {integer}
-
Write out the full type
-
long_variable_name : {'hi', 'ho'}, optional
-
Choices in brackets, default first when optional.
-
-
-

Returns:

-
-
-
named : {type}
-
Explanation
-
list
-
Explanation
-
of
-
Explanation
-
outputs
-
even more explaining
-
-
-

Other Parameters:

-
-
-
only_seldom_used_keywords : type
-
Explanation
-
common_parametrs_listed_above : type
-
Explanation
-
-
-

See Also:

-
-

otherfunc : relationship (optional)

-

newfunc : relationship (optional)

-
-

Notes

-
-

Notes about the implementation algorithm (if needed).

-

This can have multiple paragraphs as can all sections.

-
-

Examples

-
-

examples in doctest format

-
->>> a=[1,2,3]
->>> [x + 3 for x in a]
-[4, 5, 6]
-
+ 
+One-line summary or signature.
+
+Several sentences providing an extended description. You can put
+text in mono-spaced type like so: ``var``.
+
+Parameters
+----------
+var1 : array_like
+    Array_like means all those objects -- lists, nested lists, etc. --
+    that can be converted to an array.
+var2 : integer
+    Write out the full type
+long_variable_name : {'hi', 'ho'}, optional
+    Choices in brackets, default first when optional.
+
+Returns
+-------
+named : type
+    Explanation
+list
+    Explanation
+of
+    Explanation
+outputs
+    even more explaining
+
+Other Parameters
+----------------
+only_seldom_used_keywords : type
+    Explanation
+common_parametrs_listed_above : type
+    Explanation
+
+See Also
+--------    
+otherfunc : relationship (optional)
+newfunc : relationship (optional)
+
+Notes
+-----
+Notes about the implementation algorithm (if needed).
+
+This can have multiple paragraphs as can all sections.
+
+Examples
+--------
+
+examples in doctest format
+
+>>> a=[1,2,3]
+>>> [x + 3 for x in a]
+[4, 5, 6]
+
+
@@ -239,10 +239,10 @@ that can be converted to an array. source code  - +

Do nothing.

-

I never saw a purple cow.

+

I never saw a purple cow.

@@ -259,10 +259,10 @@ that can be converted to an array. source code  - +

Do nothing.

-

I never hope to see one.

+

I never hope to see one.

@@ -294,10 +294,11 @@ that can be converted to an array.
- Generated by Epydoc 3.0beta1 on Sun Sep 23 13:30:28 2007 + Generated by Epydoc 3.0beta1 on Fri Dec 28 00:50:17 2007 - http://epydoc.sourceforge.net + http://epydoc.sourceforge.net
@@ -308,9 +309,8 @@ that can be converted to an array. // javascript is turned off then we want them to be // visible); but by default, we want to hide them. So hide // them unless we have a cookie that says to show them. - checkCookie() + checkCookie(); // --> - diff --git a/numpy/doc/html/example-pysrc.html b/numpy/doc/html/example-pysrc.html index 0790bad92..ded35ac87 100644 --- a/numpy/doc/html/example-pysrc.html +++ b/numpy/doc/html/example-pysrc.html @@ -55,105 +55,101 @@

Source Code for Module example

-  1  """This is the docstring for the example.py module.  Modules names should 
-  2  have short, all-lowercase names.  The module name may have underscores if 
-  3  this improves readability. 
-  4   
-  5  Every module should have a docstring at the very top of the file.  The 
-  6  module's docstring may extend over multiple lines.  If your docstring does 
-  7  extend over multiple lines, the closing three quotation marks must be on 
-  8  a line by itself, preferably preceeded by a blank line. 
-  9   
- 10  """ 
- 11   
- 12  import os                      # standard library imports first 
- 13   
- 14  import numpy as np             # related third party imports next 
- 15  import scipy as sp             # imports should be at the top of the module 
- 16  import matplotlib as mpl       # imports should usually be on separate lines 
- 17   
- 18   
- 19  __docformat__ = "restructuredtext en" 
- 20   
- 21   
-
 22 -def foo(var1, var2, long_var_name='hi') : 
-
 23      """One-line summary or signature. 
- 24   
- 25      Several sentences providing an extended description. You can put 
- 26      text in mono-spaced type like so: ``var``. 
- 27   
- 28      *Parameters*: 
- 29   
- 30          var1 : {array_like} 
- 31              Array_like means all those objects -- lists, nested lists, etc. -- 
- 32              that can be converted to an array. 
- 33          var2 : {integer} 
- 34              Write out the full type 
- 35          long_variable_name : {'hi', 'ho'}, optional 
- 36              Choices in brackets, default first when optional. 
- 37   
- 38      *Returns*: 
- 39   
- 40          named : {type} 
- 41              Explanation 
- 42          list 
- 43              Explanation 
- 44          of 
- 45              Explanation 
- 46          outputs 
- 47              even more explaining 
- 48   
- 49      *Other Parameters*: 
- 50   
- 51          only_seldom_used_keywords : type 
- 52              Explanation 
- 53          common_parametrs_listed_above : type 
- 54              Explanation 
- 55   
- 56      *See Also*: 
- 57   
- 58          `otherfunc` : relationship (optional) 
- 59   
- 60          `newfunc` : relationship (optional) 
- 61   
- 62      *Notes* 
- 63   
- 64          Notes about the implementation algorithm (if needed). 
- 65   
- 66          This can have multiple paragraphs as can all sections. 
- 67   
- 68      *Examples* 
- 69   
- 70          examples in doctest format 
- 71   
- 72          >>> a=[1,2,3] 
- 73          >>> [x + 3 for x in a] 
- 74          [4, 5, 6] 
- 75   
- 76      """ 
- 77   
- 78      pass 
-
 79   
- 80   
-
 81 -def newfunc() : 
-
 82      """Do nothing. 
- 83   
- 84      I never saw a purple cow. 
- 85   
- 86      """ 
- 87   
- 88      pass 
-
 89   
- 90   
-
 91 -def otherfunc() : 
-
 92      """Do nothing. 
- 93   
- 94      I never hope to see one. 
- 95   
- 96      """ 
- 97   
- 98      pass 
-
 99   
-  
 
 
diff --git a/numpy/doc/html/help.html b/numpy/doc/html/help.html
index 8c56960b5..2329f20a7 100644
--- a/numpy/doc/html/help.html
+++ b/numpy/doc/html/help.html
@@ -246,10 +246,11 @@ page was last updated. 

 

   

     
-    Generated by Epydoc 3.0beta1 on Sun Sep 23 13:30:28 2007
+    Generated by Epydoc 3.0beta1 on Fri Dec 28 00:50:17 2007
     
     
-      http://epydoc.sourceforge.net
+      http://epydoc.sourceforge.net
     
   

 

@@ -260,9 +261,8 @@ page was last updated. 

   // javascript is turned off then we want them to be
   // visible); but by default, we want to hide them.  So hide
   // them unless we have a cookie that says to show them.
-  checkCookie()
+  checkCookie();
   // -->
 
-  
 
 
diff --git a/numpy/doc/html/identifier-index.html b/numpy/doc/html/identifier-index.html
index 317e1677b..9a4fce613 100644
--- a/numpy/doc/html/identifier-index.html
+++ b/numpy/doc/html/identifier-index.html
@@ -158,10 +158,11 @@
 

   

     
-    Generated by Epydoc 3.0beta1 on Sun Sep 23 13:30:28 2007
+    Generated by Epydoc 3.0beta1 on Fri Dec 28 00:50:17 2007
     
     
-      http://epydoc.sourceforge.net
+      http://epydoc.sourceforge.net
     
   

 

@@ -172,9 +173,8 @@
   // javascript is turned off then we want them to be
   // visible); but by default, we want to hide them.  So hide
   // them unless we have a cookie that says to show them.
-  checkCookie()
+  checkCookie();
   // -->
 
-  
 
 
diff --git a/numpy/doc/html/module-tree.html b/numpy/doc/html/module-tree.html
index db41e8d35..3a3dbc287 100644
--- a/numpy/doc/html/module-tree.html
+++ b/numpy/doc/html/module-tree.html
@@ -79,10 +79,11 @@
 

   

     
-    Generated by Epydoc 3.0beta1 on Sun Sep 23 13:30:28 2007
+    Generated by Epydoc 3.0beta1 on Fri Dec 28 00:50:17 2007
     
     
-      http://epydoc.sourceforge.net
+      http://epydoc.sourceforge.net
     
   

 

@@ -93,9 +94,8 @@
   // javascript is turned off then we want them to be
   // visible); but by default, we want to hide them.  So hide
   // them unless we have a cookie that says to show them.
-  checkCookie()
+  checkCookie();
   // -->
 
-  
 
 
diff --git a/numpy/doc/html/toc-everything.html b/numpy/doc/html/toc-everything.html
index f6ed84f8e..ce94bd1f0 100644
--- a/numpy/doc/html/toc-everything.html
+++ b/numpy/doc/html/toc-everything.html
@@ -26,9 +26,8 @@
   // javascript is turned off then we want them to be
   // visible); but by default, we want to hide them.  So hide
   // them unless we have a cookie that says to show them.
-  checkCookie()
+  checkCookie();
   // -->
 
-  
 
 
diff --git a/numpy/doc/html/toc-example-module.html b/numpy/doc/html/toc-example-module.html
index 137dea5ae..c691dccae 100644
--- a/numpy/doc/html/toc-example-module.html
+++ b/numpy/doc/html/toc-example-module.html
@@ -26,9 +26,8 @@
   // javascript is turned off then we want them to be
   // visible); but by default, we want to hide them.  So hide
   // them unless we have a cookie that says to show them.
-  checkCookie()
+  checkCookie();
   // -->
 
-  
 
 
diff --git a/numpy/doc/html/toc.html b/numpy/doc/html/toc.html
index d9863817f..7008e1695 100644
--- a/numpy/doc/html/toc.html
+++ b/numpy/doc/html/toc.html
@@ -26,9 +26,8 @@
   // javascript is turned off then we want them to be
   // visible); but by default, we want to hide them.  So hide
   // them unless we have a cookie that says to show them.
-  checkCookie()
+  checkCookie();
   // -->
 
-  
 
 
-- 
cgit v1.2.1