Nicer formatting for the PDU field documentation

specification/30_server_server_api.rst

@@ -110,8 +110,9 @@ receiving an "empty" transaction.)
 
 PDUs and EDUs
 -------------
-.. WARNING::
+
-  This section may be misleading or inaccurate.
+Common PDU Fields
+~~~~~~~~~~~~~~~~~
 
 All PDUs have:
  - An ID
@@ -121,47 +122,55 @@ All PDUs have:
    (regardless of which origin sent them)
 
 ``context``
-  Type:
++++++++++++
+Type:
   String
-  Description:
+Description:
   Event context identifier
 
+
 ``origin``
-  Type:
+++++++++++
+Type:
   String
-  Description:
+Description:
   DNS name of homeserver that created this PDU.
 
 ``pdu_id``
-  Type:
+++++++++++
+Type:
   String
-  Description:
+Description:
   Unique identifier for PDU within the context for the originating homeserver
 
 ``ts``
-  Type:
+++++++
+Type:
   Integer
-  Description:
+Description:
   Timestamp in milliseconds on originating homeserver when this PDU was
   created.
 
 ``pdu_type``
-  Type:
+++++++++++++
+Type:
   String
-  Description:
+Description:
   PDU event type.
 
 ``prev_pdus``
-  Type:
++++++++++++++
+Type:
   List of pairs of strings
-  Description:
+Description:
   The originating homeserver and PDU ids of the most recent PDUs the
   homeserver was aware of for this context when it made this PDU.
 
 ``depth``
-  Type:
++++++++++
+Type:
   Integer
-  Description:
+Description:
   The maximum depth of the previous PDUs plus one.
 
 
@@ -169,48 +178,58 @@ All PDUs have:
   - Update this structure so that 'pdu_id' is a two-element [origin,ref] pair
     like the prev_pdus are
 
+State Update PDU Fields
+~~~~~~~~~~~~~~~~~~~~~~~
+
 For state updates:
 
 ``is_state``
-  Type:
+++++++++++++
+Type:
   Boolean
-  Description:
+Description:
   True if this PDU is updating state.
 
 ``state_key``
-  Type:
++++++++++++++
+Type:
   String
-  Description:
+Description:
   Optional key identifying the updated state within the context.
 
 ``power_level``
-  Type:
++++++++++++++++
+Type:
   Integer
-  Description:
+Description:
   The asserted power level of the user performing the update.
 
 ``required_power_level``
-  Type:
+++++++++++++++++++++++++
+Type:
   Integer
-  Description:
+Description:
   The required power level needed to replace this update.
 
 ``prev_state_id``
-  Type:
++++++++++++++++++
+Type:
   String
-  Description:
+Description:
   PDU event type.
 
 ``prev_state_origin``
-  Type:
++++++++++++++++++++++
+Type:
   String
-  Description:
+Description:
   The PDU id of the update this replaces.
 
 ``user_id``
-  Type:
++++++++++++
+Type:
   String
-  Description:
+Description:
   The user updating the state.
 
 ::