widelands-dev team mailing list archive

[kaputtnik <somal@xxxxxxxx>]

kaputtnik has proposed merging lp:~widelands-dev/widelands/fix_RST_comments into lp:widelands.

Commit message:
- Fixes for misaligned RST comments which appear after running clang-format.
- Changed the black coloring of formulas

Requested reviews:
  Widelands Developers (widelands-dev)

For more details, see:
https://code.launchpad.net/~widelands-dev/widelands/fix_RST_comments/+merge/302205

- Fixes for misaligned RST comments which appear after running clang-format.
- Changed the black coloring of formulas in https://wl.widelands.org/docs/wl/geometry/ 
   The bottom color from this example is used now https://bugs.launchpad.net/widelands-website/+bug/1512093/+attachment/4712556/+files/sphinx_formula_coloring.jpg

This branch may need also a modified clang config file to prevent such misaligning in future when running clang-format. See comment 20 in https://bugs.launchpad.net/widelands-website/+bug/1512093
I couldn't make such a config-file.
-- 
Your team Widelands Developers is requested to review the proposed merge of lp:~widelands-dev/widelands/fix_RST_comments into lp:widelands.

=== modified file 'doc/sphinx/source/conf.py'
--- doc/sphinx/source/conf.py	2012-06-15 20:29:49 +0000
+++ doc/sphinx/source/conf.py	2016-08-06 12:59:52 +0000
@@ -25,7 +25,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.pngmath']
+extensions = ['sphinx.ext.imgmath']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -240,3 +240,9 @@
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+# Options for displaying formulas
+# http://www.nongnu.org/dvipng/dvipng_4.html#Command_002dline-options
+# Use one of 'dvispnames' or 'svgnames' for coloring from
+# http://mirrors.ctan.org/macros/latex/contrib/xcolor/xcolor.pdf
+imgmath_dvipng_args = ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent', '-fg', 'Cerulean']

=== modified file 'src/scripting/lua_globals.cc'
--- src/scripting/lua_globals.cc	2016-08-04 15:49:05 +0000
+++ src/scripting/lua_globals.cc	2016-08-06 12:59:52 +0000
@@ -195,8 +195,7 @@
 /* RST
 .. function:: pgettext(msgctxt, msgid)
 
-   A wrapper for the pgettext() function, needed for allowing multiple translations of the same
-string
+   A wrapper for the pgettext() function, needed for allowing multiple translations of the same string
    according to context.
 
    :arg msgctxt: a named context for this string for disambiguation
@@ -204,7 +203,7 @@
    :arg msgid: text to translate
    :type msgid: :class:`string`
 
-   :returns: The translated string.
+	:returns: The translated string.
 */
 // UNTESTED
 static int L_pgettext(lua_State* L) {

=== modified file 'src/scripting/lua_map.cc'
--- src/scripting/lua_map.cc	2016-08-04 15:49:05 +0000
+++ src/scripting/lua_map.cc	2016-08-06 12:59:52 +0000
@@ -1097,9 +1097,8 @@
 /* RST
    .. attribute:: buildings
 
-         (RO) an array of :class:`LuaBuildingDescription` with all the buildings that the tribe can
-   use,
-              casted to their appropriate subclasses.
+      (RO) an array of :class:`LuaBuildingDescription` with all the buildings that the tribe can use,
+      casted to their appropriate subclasses.
 */
 int LuaTribeDescription::get_buildings(lua_State* L) {
 	const TribeDescr& tribe = *get();
@@ -1161,8 +1160,7 @@
 /* RST
    .. attribute:: headquarters
 
-         (RO) the :class:`string` internal name of the default headquarters type that this tribe
-   uses
+         (RO) the :class:`string` internal name of the default headquarters type that this tribe uses
 */
 
 int LuaTribeDescription::get_headquarters(lua_State* L) {
@@ -1300,14 +1298,13 @@
 
 .. class:: MapObjectDescription
 
-   A static description of a tribe's map object, so it can be used in help files
-   without having to access an actual object on the map.
-   This class contains the properties that are common to all map objects such as buildings or wares.
+	A static description of a tribe's map object, so it can be used in help files
+	without having to access an actual object on the map.
+	This class contains the properties that are common to all map objects such as buildings or wares.
 
-   The dynamic MapObject class corresponding to this class is the base class for all Objects in
-widelands,
-   including immovables and Bobs. This class can't be instantiated directly, but provides the base
-   for all others.
+	The dynamic MapObject class corresponding to this class is the base class for all Objects in widelands,
+	including immovables and Bobs. This class can't be instantiated directly, but provides the base
+	for all others.
 */
 const char LuaMapObjectDescription::className[] = "MapObjectDescription";
 const MethodType<LuaMapObjectDescription> LuaMapObjectDescription::Methods[] = {
@@ -1453,10 +1450,9 @@
 }
 
 /* RST
-   .. attribute:: the name and descname of the editor category of this immovable
+	.. attribute:: the name and descname of the editor category of this immovable
 
-         (RO) a table with "name" and "descname" entries for the editor category, or nil if it has
-   none.
+			(RO) a table with "name" and "descname" entries for the editor category, or nil if it has none.
 */
 int LuaImmovableDescription::get_editor_category(lua_State* L) {
 	const EditorCategory* editor_category = get()->editor_category();
@@ -1475,12 +1471,11 @@
 }
 
 /* RST
-   .. attribute:: returns the terrain affinity values for this immovable
+	.. attribute:: returns the terrain affinity values for this immovable
 
-         (RO) a table containing numbers labeled as pickiness (double), preferred_fertility
-   (double),
-              preferred_humidity (double), and preferred_temperature (uint),
-              or nil if the immovable has no terrain affinity.
+			(RO) a table containing numbers labeled as pickiness (double), preferred_fertility (double),
+				  preferred_humidity (double), and preferred_temperature (uint),
+				  or nil if the immovable has no terrain affinity.
 */
 int LuaImmovableDescription::get_terrain_affinity(lua_State* L) {
 	if (get()->has_terrain_affinity()) {
@@ -1704,8 +1699,7 @@
 /* RST
    .. attribute:: enhanced_from
 
-         (RO) returns the building that this was enhanced from, or nil if this isn't an enhanced
-   building.
+         (RO) returns the building that this was enhanced from, or nil if this isn't an enhanced building.
 */
 int LuaBuildingDescription::get_enhanced_from(lua_State* L) {
 	if (get()->is_enhanced()) {
@@ -1986,15 +1980,13 @@
 }
 
 /* RST
-   .. attribute:: consumed_wares
-
-      :arg program_name: the name of the production program that we want to get the consumed wares
-   for
-      :type tribename: :class:`string`
-
-      (RO) Returns a table of {{ware name}, ware amount} for the wares consumed by this production
-   program.
-           Multiple entries in {ware name} are alternatives (OR logic)).
+	.. attribute:: consumed_wares
+
+		:arg program_name: the name of the production program that we want to get the consumed wares for
+		:type tribename: :class:`string`
+
+		(RO) Returns a table of {{ware name}, ware amount} for the wares consumed by this production program.
+			  Multiple entries in {ware name} are alternatives (OR logic)).
 */
 int LuaProductionSiteDescription::consumed_wares(lua_State* L) {
 	std::string program_name = luaL_checkstring(L, -1);
@@ -2018,14 +2010,12 @@
 }
 
 /* RST
-   .. attribute:: produced_wares
-
-      :arg program_name: the name of the production program that we want to get the produced wares
-   for
-      :type tribename: :class:`string`
-
-      (RO) Returns a table of {ware name, ware amount} for the wares produced by this production
-   program
+	.. attribute:: produced_wares
+
+		:arg program_name: the name of the production program that we want to get the produced wares for
+		:type tribename: :class:`string`
+
+		(RO) Returns a table of {ware name, ware amount} for the wares produced by this production program
 */
 int LuaProductionSiteDescription::produced_wares(lua_State* L) {
 	std::string program_name = luaL_checkstring(L, -1);
@@ -2038,14 +2028,13 @@
 }
 
 /* RST
-   .. attribute:: recruited_workers
-
-      :arg program_name: the name of the production program that we want to get the recruited
-   workers for
-      :type tribename: :class:`string`
-
-      (RO) Returns a table of {worker name, worker amount} for the workers recruited
-           by this production program
+	.. attribute:: recruited_workers
+
+		:arg program_name: the name of the production program that we want to get the recruited workers for
+		:type tribename: :class:`string`
+
+		(RO) Returns a table of {worker name, worker amount} for the workers recruited
+			  by this production program
 */
 int LuaProductionSiteDescription::recruited_workers(lua_State* L) {
 	std::string program_name = luaL_checkstring(L, -1);
@@ -2112,11 +2101,10 @@
 
 .. class:: TrainingSiteDescription
 
-   A static description of a tribe's trainingsite, so it can be used in help files
-   without having to access an actual building on the map.
-   A training site can train some or all of a soldier's properties (Attack, Defense, Evade and
-Health).
-   See also class BuildingDescription and class MapObjectDescription for more properties.
+	A static description of a tribe's trainingsite, so it can be used in help files
+	without having to access an actual building on the map.
+	A training site can train some or all of a soldier's properties (Attack, Defense, Evade and Health).
+	See also class BuildingDescription and class MapObjectDescription for more properties.
 */
 const char LuaTrainingSiteDescription::className[] = "TrainingSiteDescription";
 const MethodType<LuaTrainingSiteDescription> LuaTrainingSiteDescription::Methods[] = {
@@ -2909,12 +2897,11 @@
  */
 
 /* RST
-   .. method:: editor_image(amount)
-
-      :arg amount: The amount of the resource what we want an overlay image for
-
-         (RO) the :class:`string` path to the image representing the specified amount of this
-   resource
+	.. method:: editor_image(amount)
+
+		:arg amount: The amount of the resource what we want an overlay image for
+
+			(RO) the :class:`string` path to the image representing the specified amount of this resource
 */
 int LuaResourceDescription::editor_image(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -2990,11 +2977,10 @@
 }
 
 /* RST
-   .. attribute:: get_default_resource
+	.. attribute:: get_default_resource
 
-         (RO) the :class:`wl.map.ResourceDescription` for the default resource provided by this
-   terrain, or
-              nil if the terrain has no default resource.
+			(RO) the :class:`wl.map.ResourceDescription` for the default resource provided by this terrain, or
+				  nil if the terrain has no default resource.
 */
 
 int LuaTerrainDescription::get_default_resource(lua_State* L) {
@@ -3021,10 +3007,9 @@
 }
 
 /* RST
-   .. attribute:: the name and descname of the editor category of this terrain
+	.. attribute:: the name and descname of the editor category of this terrain
 
-         (RO) a table with "name" and "descname" entries for the editor category, or nil if it has
-   none.
+			(RO) a table with "name" and "descname" entries for the editor category, or nil if it has none.
 */
 int LuaTerrainDescription::get_editor_category(lua_State* L) {
 	const EditorCategory* editor_category = get()->editor_category();
@@ -3087,10 +3072,9 @@
 }
 
 /* RST
-   .. attribute:: valid_resources
+	.. attribute:: valid_resources
 
-         (RO) a list of :class:`wl.map.ResourceDescription` with all valid resources for this
-   terrain.
+			(RO) a list of :class:`wl.map.ResourceDescription` with all valid resources for this terrain.
 */
 
 int LuaTerrainDescription::get_valid_resources(lua_State* L) {