Merge pull request pygame#518 from pygame/docs-header-cleanup

Organise the docs modules by usage, add search form.

docs/reST/ref/math.rst

@@ -46,7 +46,7 @@ New in pygame 1.9.2pre.
    .. method:: cross
 
       | :sl:`calculates the cross- or vector-product`
-      | :sg:`cross(Vector2) -> float`
+      | :sg:`cross(Vector2) -> Vector2`
 
       calculates the third component of the cross-product.
 
@@ -277,7 +277,7 @@ New in pygame 1.9.2pre.
    .. method:: cross
 
       | :sl:`calculates the cross- or vector-product`
-      | :sg:`cross(Vector3) -> float`
+      | :sg:`cross(Vector3) -> Vector3`
 
       calculates the cross-product.
 

docs/reST/ref/midi.rst

@@ -149,6 +149,20 @@ New in pygame 1.9.0.
 
       .. ## Output.set_instrument ##
 
+   .. method:: pitch_bend
+
+      | :sl:`modify the pitch of a channel.`
+      | :sg:`set_instrument(value = 0, channel = 0) -> None`
+
+      Adjust the pitch of a channel.  The value is a signed integer
+      from -8192 to +8191.  For example, 0 means "no change", +4096 is
+      typically a semitone higher, and -8192 is 1 whole tone lower (though
+      the musical range corresponding to the pitch bend range can also be
+      changed in some synthesizers).
+
+      If no value is given, the pitch bend is returned to "no change".
+      New in pygame 1.9.4.
+
    .. method:: write
 
       | :sl:`writes a list of midi data to the Output`

docs/reST/themes/classic/elements.html

@@ -18,13 +18,42 @@
 	  <h5>pygame documentation</h5>
 	</td>
 	<td class="pagelinks">
-	  <p class="top">
+	  <div class="top">
 	    <a href="{{ theme_home_uri }}">Pygame Home</a> ||
 	    <a href="{{ pathto(master_doc) }}">Help Contents</a> ||
 	    <a href="{{ pathto('genindex') }}">Reference Index</a>
-	  </p>
+
+        <form action="{{ pathto('search') }}" method="get" style="display:inline;float:right;">
+          <input name="q" value="" type="text">
+          <input value="search" type="submit">
+        </form>
+	  </div>
+	  <hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
+{#-
+
+We render three sets of items based on how useful to most apps.
+
+#}
+{%- set basic = ['Color', 'display', 'draw', 'event', 'font', 'image', 'key', 'locals', 'mixer', 'mouse', 'music', 'pygame', 'Rect', 'Surface', 'time'] %}
+{%- set advanced = ['BufferProxy', 'freetype', 'gfxdraw', 'midi', 'Overlay', 'PixelArray', 'pixelcopy', 'sndarray', 'surfarray', 'cursors', 'joystick', 'mask', 'math', 'sprite', 'transform'] %}
 {%-   if pyg_sections %}
-	  <p class="bottom">
+	  <p class="bottom"><b>Most useful stuff</b>:
+{%      set sep = joiner(" | \n") %}
+{%-     for section in pyg_sections %}
+{%-       set docname = section['docname'] %}
+{%-       set simpledocname = docname.split('/')[-1] %}
+{%-       set name = section['fullname'].split('.')[-1] %}
+{%-       set uri = pathto(docname, 1) + file_suffix -%}
+{%-       if name|lower != simpledocname %}
+{%-         set uri = uri + '#' + section['refid'] %}
+{%-       endif %}
+{%-       if name in basic %}
+{{- sep() }}	    <a href="{{ uri }}">{{ name }}</a>
+{%-       endif %}
+{%-     endfor %}
+	  </p>
+
+	  <p class="bottom"><b>Advanced stuff</b>:
 {%      set sep = joiner(" | \n") %}
 {%-     for section in pyg_sections %}
 {%-       set docname = section['docname'] %}
@@ -34,9 +63,30 @@ <h5>pygame documentation</h5>
 {%-       if name|lower != simpledocname %}
 {%-         set uri = uri + '#' + section['refid'] %}
 {%-       endif %}
+{%-       if name in advanced %}
 {{- sep() }}	    <a href="{{ uri }}">{{ name }}</a>
+{%-       endif %}
+{%-     endfor %}
+	  </p>
+
+	  <p class="bottom"><b>Other</b>:
+{%      set sep = joiner(" | \n") %}
+{%-     for section in pyg_sections %}
+{%-       set docname = section['docname'] %}
+{%-       set simpledocname = docname.split('/')[-1] %}
+{%-       set name = section['fullname'].split('.')[-1] %}
+{%-       set uri = pathto(docname, 1) + file_suffix -%}
+{%-       if name|lower != simpledocname %}
+{%-         set uri = uri + '#' + section['refid'] %}
+{%-       endif %}
+{%-       if name not in basic and name not in advanced %}
+{{- sep() }}	    <a href="{{ uri }}">{{ name }}</a>
+{%-       endif %}
 {%-     endfor %}
 	  </p>
+
+
+
 {%-   endif  %}
 	</td>
       </tr>

docs/reST/themes/classic/static/pygame.css_t

@@ -119,7 +119,7 @@ div.body table.matrix td {
     border-right: 0.1em solid black;
 }
 
-div.body table.matrix th:last-child, 
+div.body table.matrix th:last-child,
 div.body table.matrix td:last-child {
     border-right-style: none;
 }
@@ -230,11 +230,12 @@ div.header p.top {
 
 div.header p.bottom {
     margin-bottom: 0;
+    text-align: left;
 }
 
 div.header .pagelinks a {
     text-decoration: underline;
-}    
+}
 
 div.header .pagelinks a:hover {
     text-decoration: none;
@@ -411,7 +412,7 @@ dl.definition {
 dd {
     margin-left: 30px;
 }
- 
+
 dt tt {
     font-weight: bold;
     font-size: 1.1em;
@@ -763,7 +764,7 @@ header.commentHeading {
     text-align: center;
 }
 pre.commentContent {
-    overflow: auto; 
+    overflow: auto;
     max-width; 800px;
     margin-left:0px;
     border: 0;

src_c/doc/math_doc.h

@@ -5,7 +5,7 @@
 
 #define DOC_VECTOR2DOT "dot(Vector2) -> float\ncalculates the dot- or scalar-product with the other vector"
 
-#define DOC_VECTOR2CROSS "cross(Vector2) -> float\ncalculates the cross- or vector-product"
+#define DOC_VECTOR2CROSS "cross(Vector2) -> Vector2\ncalculates the cross- or vector-product"
 
 #define DOC_VECTOR2MAGNITUDE "magnitude() -> float\nreturns the Euclidean magnitude of the vector."
 
@@ -51,7 +51,7 @@
 
 #define DOC_VECTOR3DOT "dot(Vector3) -> float\ncalculates the dot- or scalar-product with the other vector"
 
-#define DOC_VECTOR3CROSS "cross(Vector3) -> float\ncalculates the cross- or vector-product"
+#define DOC_VECTOR3CROSS "cross(Vector3) -> Vector3\ncalculates the cross- or vector-product"
 
 #define DOC_VECTOR3MAGNITUDE "magnitude() -> float\nreturns the Euclidean magnitude of the vector."
 
@@ -132,7 +132,7 @@ pygame.math.Vector2.dot
 calculates the dot- or scalar-product with the other vector
 
 pygame.math.Vector2.cross
- cross(Vector2) -> float
+ cross(Vector2) -> Vector2
 calculates the cross- or vector-product
 
 pygame.math.Vector2.magnitude
@@ -229,7 +229,7 @@ pygame.math.Vector3.dot
 calculates the dot- or scalar-product with the other vector
 
 pygame.math.Vector3.cross
- cross(Vector3) -> float
+ cross(Vector3) -> Vector3
 calculates the cross- or vector-product
 
 pygame.math.Vector3.magnitude

src_c/doc/midi_doc.h

@@ -23,6 +23,8 @@
 
 #define DOC_OUTPUTSETINSTRUMENT "set_instrument(instrument_id, channel = 0) -> None\nselect an instrument, with a value between 0 and 127"
 
+#define DOC_OUTPUTPITCHBEND "set_instrument(value = 0, channel = 0) -> None\nmodify the pitch of a channel."
+
 #define DOC_OUTPUTWRITE "write(data) -> None\nwrites a list of midi data to the Output"
 
 #define DOC_OUTPUTWRITESHORT "write_short(status) -> None\nwrite_short(status, data1 = 0, data2 = 0) -> None\nwrite_short(status <, data1><, data2>)"
@@ -102,6 +104,10 @@ pygame.midi.Output.set_instrument
  set_instrument(instrument_id, channel = 0) -> None
 select an instrument, with a value between 0 and 127
 
+pygame.midi.Output.pitch_bend
+ set_instrument(value = 0, channel = 0) -> None
+modify the pitch of a channel.
+
 pygame.midi.Output.write
  write(data) -> None
 writes a list of midi data to the Output