Fix a bunch of inconsistencies in the documentation

doc/KerboscriptLexer.py

@@ -4,11 +4,10 @@
 
 import re
 
-from pygments.lexer import RegexLexer, include, bygroups, using, \
-    this, inherit, default, words
-from pygments.util import get_bool_opt
+from pygments.lexer import RegexLexer, words
 from pygments.token import Text, Comment, Operator, Keyword, Name, String, \
-    Number, Punctuation, Error
+    Number, Punctuation
+from sphinx.highlighting import lexers
 
 class KerboscriptLexer(RegexLexer):
 
@@ -66,4 +65,4 @@ class KerboscriptLexer(RegexLexer):
     }
 
 def setup(app):
-    app.add_lexer("kerboscript", KerboscriptLexer())
+    lexers['kerboscript'] = KerboscriptLexer()

doc/ksdomain.py

@@ -3,18 +3,15 @@
 import sys
 import re
 
-from docutils import nodes
-from docutils.parsers.rst import directives
-
 from sphinx import addnodes, version_info
 from sphinx.roles import XRefRole
-from sphinx.locale import l_, _
-from sphinx.domains import Domain, ObjType, Index
+from sphinx.locale import _
+from sphinx.domains import Domain, ObjType
 from sphinx.directives import ObjectDescription
 from sphinx.util.nodes import make_refnode
 # ### Next line is deprecated, and it seems to work without it, as per kOS PR #2339 ###
 # from sphinx.util.compat import Directive
-from sphinx.util.docfields import Field, GroupedField, TypedField
+from sphinx.util.docfields import Field, TypedField
 
 ks_sig_re = re.compile(r'''
     (?:
@@ -68,8 +65,8 @@ def add_target_and_index(self, name, sig, signode):
 
 class KOSGlobal(KOSObject):
     doc_field_types = [
-        Field('access', label=l_('Access'), has_arg=False),
-        Field('type'  , label=l_('Type'  ), has_arg=False),
+        Field('access', label=_('Access'), has_arg=False),
+        Field('type'  , label=_('Type'  ), has_arg=False),
     ]
 
     def handle_signature(self, sig, signode):
@@ -86,13 +83,13 @@ def get_index_text(self, objectname, name):
 
 class KOSFunction(KOSObject):
     doc_field_types = [
-        Field('access', label=l_('Access'), has_arg=False),
-        TypedField('parameter', label=l_('Parameters'),
+        Field('access', label=_('Access'), has_arg=False),
+        TypedField('parameter', label=_('Parameters'),
                    names=('param', 'parameter', 'arg', 'argument'),
                    typerolename='struct', typenames=('paramtype', 'type')),
-        Field('returnvalue', label=l_('Returns'), has_arg=False,
+        Field('returnvalue', label=_('Returns'), has_arg=False,
               names=('returns', 'return')),
-        Field('returntype', label=l_('Return type'), has_arg=False,
+        Field('returntype', label=_('Return type'), has_arg=False,
               names=('rtype','type')),
     ]
 
@@ -114,7 +111,7 @@ def get_index_text(self, objectname, name):
 
 class KOSKeyword(KOSObject):
     doc_field_types = [
-        TypedField('parameter', label=l_('Parameters'),
+        TypedField('parameter', label=_('Parameters'),
                    names=('param', 'parameter', 'arg', 'argument'),
                    typerolename='struct', typenames=('paramtype', 'type')),
     ]
@@ -148,8 +145,8 @@ def after_content(self):
 class KOSAttribute(KOSObject):
 
     doc_field_types = [
-        Field('access', label=l_('Access'), has_arg=False),
-        Field('type'  , label=l_('Type'  ), has_arg=False),
+        Field('access', label=_('Access'), has_arg=False),
+        Field('type'  , label=_('Type'  ), has_arg=False),
     ]
 
     def handle_signature(self, sig, signode):
@@ -185,13 +182,13 @@ def get_index_text(self, objectname, name):
 class KOSMethod(KOSObject):
 
     doc_field_types = [
-        Field('access', label=l_('Access'), has_arg=False),
-        TypedField('parameter', label=l_('Parameters'),
+        Field('access', label=_('Access'), has_arg=False),
+        TypedField('parameter', label=_('Parameters'),
                    names=('param', 'parameter', 'arg', 'argument'),
                    typerolename='obj', typenames=('paramtype', 'type')),
-        Field('returnvalue', label=l_('Returns'), has_arg=False,
+        Field('returnvalue', label=_('Returns'), has_arg=False,
               names=('returns', 'return')),
-        Field('returntype', label=l_('Return type'), has_arg=False,
+        Field('returntype', label=_('Return type'), has_arg=False,
               names=('rtype','type')),
     ]
 
@@ -267,12 +264,12 @@ class KOSDomain(Domain):
     }
 
     object_types = {
-        'global'   : ObjType(l_('global'   ), 'global'),
-        'function' : ObjType(l_('function' ), 'func'  ),
-        'keyword'  : ObjType(l_('keyword'  ), 'key'   ),
-        'structure': ObjType(l_('structure'), 'struct'),
-        'attribute': ObjType(l_('attribure'), 'attr'  ),
-        'method'   : ObjType(l_('method'   ), 'meth'  ),
+        'global'   : ObjType(_('global'   ), 'global'),
+        'function' : ObjType(_('function' ), 'func'  ),
+        'keyword'  : ObjType(_('keyword'  ), 'key'   ),
+        'structure': ObjType(_('structure'), 'struct'),
+        'attribute': ObjType(_('attribure'), 'attr'  ),
+        'method'   : ObjType(_('method'   ), 'meth'  ),
     }
     directives = {
         'global'   : KOSGlobal,

doc/source/bindings.rst

@@ -533,7 +533,7 @@ For Kerbals, it refers to a more arbitrary line in space, pointing at a fixed
 point in the firmament, also known as the "skybox".
 
 OPCODESLEFT
----------
+-----------
 
 This returns the amount of IPU that are left in this physics tick. This means
 that if you receive the value 20, you can run 20 more instructions. After this
@@ -544,7 +544,7 @@ OPCODESLEFT can be used to try to make sure you run a block of code in one
 physics tick. This is useful when working with vectors or when interacting
 with shared message queues. 
 
-To use:
+To use::
 
    // Will always wait the first time, becomes more accurate the second time.
    GLOBAL OPCODESNEEDED TO 1000.

doc/source/language/variables.rst

@@ -537,12 +537,12 @@ with one of your own names.
 
 .. warning::
     .. versionadded:: 1.4.0.0
-    ** BREAKING CHANGE: **
-    kOS only started enforcing this rule in kOS 1.4.0.0 and up, so old
-    scripts you find on the internet might generate errors because of
-    this new enforcement.  See :attr:`Config:CLOBBERBUILTINS` or
-    :ref:`@CLOBBERBUILTINS <clobberbuiltins>` if you wish to disable
-    this check and get the old behavior back.
+        ** BREAKING CHANGE: **
+        kOS only started enforcing this rule in kOS 1.4.0.0 and up, so old
+        scripts you find on the internet might generate errors because of
+        this new enforcement.  See :attr:`Config:CLOBBERBUILTINS` or
+        :ref:`@CLOBBERBUILTINS <clobberbuiltins>` if you wish to disable
+        this check and get the old behavior back.
 
 For example, because kOS has the built-in function :func:`V(x,y,z)`,
 which makes a vector, you shouldn't make a user defined function

doc/source/math/basic.rst

@@ -535,7 +535,7 @@ Trigonometric Functions
 
 .. function:: ARCSIN(x)
 
-    :parameter x: (:ref:`scalar <scalar>`)
+    :parameter x: (:struct:`Scalar`)
     :return: (deg) angle whose sine is x
 
     ::
@@ -544,7 +544,7 @@ Trigonometric Functions
 
 .. function:: ARCCOS(x)
 
-    :parameter x: (:ref:`scalar <scalar>`)
+    :parameter x: (:struct:`Scalar`)
     :return: (deg) angle whose cosine is x
 
     ::
@@ -553,7 +553,7 @@ Trigonometric Functions
 
 .. function:: ARCTAN(x)
 
-    :parameter x: (:ref:`scalar <scalar>`)
+    :parameter x: (:struct:`Scalar`)
     :return: (deg) angle whose tangent is x
 
     ::
@@ -562,8 +562,8 @@ Trigonometric Functions
 
 .. function:: ARCTAN2(y,x)
 
-    :parameter y: (:ref:`scalar <scalar>`)
-    :parameter x: (:ref:`scalar <scalar>`)
+    :parameter y: (:struct:`Scalar`)
+    :parameter x: (:struct:`Scalar`)
     :return: (deg) angle whose tangent is :math:`\frac{y}{x}`
 
     ::

doc/source/math/direction.rst

@@ -139,9 +139,9 @@ Structure
     ========================= ======================= ================================
      Suffix                   Type                    Description
     ========================= ======================= ================================
-     :attr:`PITCH`            :struct:`scalar` (deg)  Rotation around :math:`x` axis
-     :attr:`YAW`              :struct:`scalar` (deg)  Rotation around :math:`y` axis
-     :attr:`ROLL`             :struct:`scalar` (deg)  Rotation around :math:`z` axis
+     :attr:`PITCH`            :struct:`Scalar` (deg)  Rotation around :math:`x` axis
+     :attr:`YAW`              :struct:`Scalar` (deg)  Rotation around :math:`y` axis
+     :attr:`ROLL`             :struct:`Scalar` (deg)  Rotation around :math:`z` axis
      :attr:`FOREVECTOR`       :struct:`Vector`        This Direction's forward vector (z axis after rotation).
      ``VECTOR``               :struct:`Vector`        Alias synonym for :attr:`FOREVECTOR`
      :attr:`TOPVECTOR`        :struct:`Vector`        This Direction's top vector (y axis after rotation).
@@ -222,20 +222,23 @@ You can use math operations on :struct:`Direction` objects as well. The next exa
 
 Supported Direction Operators:
 
-:Direction Multiplied by Direction:
+Direction Multiplied by Direction:
     ``Dir1 * Dir2`` - This operator returns the result of rotating Dir2 by the rotation of Dir1.  Note that the order of operations matters here.  ``Dir1*Dir2`` is not the same as ``Dir2*Dir1``.  Example::
 
-        // A direction pointing along compass heading 330, by rotating NORTH by 30 degrees around UP axis:
+        // A direction pointing along compass heading 330,
+        // by rotating NORTH by 30 degrees around UP axis:
         SET newDir TO ANGLEAXIS(30,SHIP:UP) * NORTH.
 
-:Direction Multiplied by Vector:
+Direction Multiplied by Vector:
     ``Dir * Vec`` - This operator returns the result of rotating the vector by Dir::
 
-        // What would the velocity of your ship be if it was angled 20 degrees to your left?
+        // What would the velocity of your ship be
+        // if it was angled 20 degrees to your left?
         SET Vel to ANGLEAXIS(-20,SHIP:TOPVECTOR) * SHIP:VELOCITY:ORBIT.
-        // At this point Vel:MAG and SHIP:VELOCITY:MAG should be the same, but they don't point the same way
+        // At this point Vel:MAG and SHIP:VELOCITY:MAG should be the same,
+        // but they don't point the same way
 
-:Direction Added to Direction:
+Direction Added to Direction:
     ``Dir1 + Dir2`` - This operator is less reliable because its exact behavior depends on the order of operations of the UnityEngine's X Y and Z axis rotations, and it can result in gimbal lock.
 
     It's supposed to perform a Euler rotation of one direction by another, but it's preferred to use ``Dir*Dir`` instead, as that doesn't experience gimbal lock, and does not require that you know the exact transformation order of Unity.

doc/source/math/geocoordinates.rst

@@ -49,48 +49,48 @@ Structure
           - Description
 
         * - :attr:`BODY`
-          - :ref:`body <body>` (m)
+          - :struct:`Body` (m)
 	  - none
           - The celestial body this geocoordinates is on.
         * - :attr:`LAT`
-          - :ref:`scalar <scalar>` (deg)
+          - :struct:`Scalar` (deg)
 	  - none
           - Latitude
         * - :attr:`LNG`
-          - :ref:`scalar <scalar>` (deg)
+          - :struct:`Scalar` (deg)
 	  - none
           - Longitude
         * - :attr:`DISTANCE`
-          - :ref:`scalar <scalar>` (m)
+          - :struct:`Scalar` (m)
 	  - none
           - distance from :ref:`CPU Vessel <cpu vessel>`
         * - :attr:`TERRAINHEIGHT`
-          - :ref:`scalar <scalar>` (m)
+          - :struct:`Scalar` (m)
 	  - none
           - above or below sea level
         * - :attr:`HEADING`
-          - :ref:`scalar <scalar>` (deg)
+          - :struct:`Scalar` (deg)
 	  - none
           - *absolute* heading from :ref:`CPU Vessel <cpu vessel>`
         * - :attr:`BEARING`
-          - :ref:`scalar <scalar>` (deg)
+          - :struct:`Scalar` (deg)
 	  - none
           - *relative* direction from :ref:`CPU Vessel <cpu vessel>`
         * - :attr:`POSITION`
-          - `Vector` (3D Ship-Raw coords)
+          - :struct:`Vector` (3D Ship-Raw coords)
 	  - none
           - Position of the surface point.
         * - :attr:`ALTITUDEPOSITION`
-          - `Vector` (3D Ship-Raw coords)
-	  - :ref:`scalar <scalar>` (altitude above sea level)
+          - :struct:`Vector` (3D Ship-Raw coords)
+	  - :struct:`Scalar` (altitude above sea level)
           - Position of a point above (or below) the surface point, by giving the altitude number.
         * - :attr:`VELOCITY`
           - :struct:`OrbitableVelocity`
 	  - none
           - Velocity of the surface at this point (due to the rotation of the planet/moon).
         * - :attr:`ALTITUDEVELOCITY`
           - :struct:`OrbitableVelocity`
-	  - :ref:`scalar <scalar>` (altitude above sea level)
+	  - :struct:`Scalar` (altitude above sea level)
           - Velocity of a point above (or below) the surface point, by giving the altitude number.
 
 .. note::

doc/source/math/scalar.rst

@@ -138,4 +138,3 @@ not how many places after the decimal point.  You can't have more than
 roughly 15 significant decimal digits. (It's not exactly 15 because of
 differences between binary and decimal counting, but that gives you
 a rough estimate.)
-