Incomplete work to generate config doc from config.ini

This is an incomplete attempt to allow generation of the config.ini
documentation in reference.txt. It reformats the output of
'roundup_admin.py genconfig'. So it now includes all of the
settings. Using a Makefile rule like:

  tracker_config.txt: ../roundup/configuration.py
	python3 ../roundup/scripts/roundup_admin.py \
               genconfig _temp_config.txt
	sed -e '1,8d' \
	    -e 's/^\[\([a-z]*\)\]/\n.. index:: config.ini; sections \1\n\n.. code:: ini\n\n  [\1]/' \
	    -e 's/^\([^[]\)/  \1/' \
	    _temp_config.txt > tracker_config.txt
	rm -f _temp_config.txt

results in the config.ini split by section and index links being put
in place. However some sections have a comment before the [section]
marker.  This comment is orphaned at the end of the prior section
rather than starting the new section. A simple sed won't allow the
lookahead needed to target the [section] marker and include the prior
comment block. Also there are still have some long lines generated (>
65 characters). Maybe a python script can import configuration.py and
output proper restructured text output?


reference.txt:
  add a commented out include:: tracker_config.txt directive

roundup/admin.py:
  don't require a tracker home for genconfig. So user can generate a
  clean config.ini on demand. Tracker home is still required for
  updateconfig.

roundup/configuration.py:
  wrap lines better. A number of them are generating comments > 65
  characters which is the targeted line length. This cleans up
  config.ini too, so is a good thing.

website/www/conf.py:
 ignore doc/tracker_config.ini when processing.

Author: rouilj

doc/reference.txt

@@ -116,6 +116,8 @@ Example configuration settings are below. This is a partial
 list. Documentation on all the settings is included in the
 ``config.ini`` file.
 
+.. .comment out. file generation needs more work include:: tracker_config.txt
+
 .. index:: config.ini; sections main
 
 Section **main**

roundup/admin.py

@@ -1934,6 +1934,10 @@ def run_command(self, args):
             return 0
         if command == 'templates':
             return self.do_templates(args[1:])
+            return 0
+        if command == 'genconfig':
+            return self.do_genconfig(args[1:])
+            return 0
 
         # figure what the command is
         try:

roundup/configuration.py

@@ -565,7 +565,7 @@ class OriginHeadersListOption(Option):
     """List of space seperated origin header values.
     """
 
-    class_description = "A list of space separated case sensitive origin headers 'scheme://host'."
+    class_description = "A list of space separated case sensitive\norigin headers 'scheme://host'."
 
     def set(self, _val):
         pathlist = self._value = []
@@ -1021,14 +1021,14 @@ def str2value(self, value):
             "the EMAIL_FROM_TAG goes inside the \"Foo Bar\" quotes like so:\n"
             "\"Foo Bar EMAIL_FROM_TAG\" <[email protected]>"),
         (Option, "new_web_user_roles", "User",
-            "Roles that a user gets when they register"
-            " with Web User Interface.\n"
-            "This is a comma-separated string of role names"
+            "Roles that a user gets when they register\n"
+            "with Web User Interface.\n"
+            "This is a comma-separated string of role names\n"
             " (e.g. 'Admin,User')."),
         (Option, "new_email_user_roles", "User",
-            "Roles that a user gets when they register"
-            " with Email Gateway.\n"
-            "This is a comma-separated string of role names"
+            "Roles that a user gets when they register\n"
+            "with Email Gateway.\n"
+            "This is a comma-separated string of role names\n"
             " (e.g. 'Admin,User')."),
         (Option, "obsolete_history_roles", "Admin",
             "On schema changes, properties or classes in the history may\n"
@@ -1039,24 +1039,26 @@ def str2value(self, value):
             "admin role may see these history entries, you can make them\n"
             "visible to all users by adding, e.g., the 'User' role here."),
         (Option, "error_messages_to", "user",
-            'Send error message emails to the "dispatcher", "user", '
+            'Send error message emails to the "dispatcher", "user", \n'
             'or "both" (these are the three allowed values).\n'
-            'The dispatcher is configured using the DISPATCHER_EMAIL'
+            'The dispatcher is configured using the DISPATCHER_EMAIL\n'
             ' setting.'),
         (Option, "html_version", "html4",
             "HTML version to generate. The templates are html4 by default.\n"
-            "If you wish to make them xhtml, then you'll need to change this\n"
-            "var to 'xhtml' too so all auto-generated HTML is compliant.\n"
+            "If you wish to make them xhtml, then you'll need to change\n"
+            "this setting to 'xhtml' too so all auto-generated HTML\n"
+            "is compliant.\n"
             "Allowed values: html4, xhtml"),
         (TimezoneOption, "timezone", TimezoneOption.defaulttz,
-            "Default timezone offset,"
-            " applied when user's timezone is not set.",
+            "Default timezone offset,\n"
+            "applied when user's timezone is not set.",
             ["DEFAULT_TIMEZONE"]),
         (BooleanOption, "instant_registration", "no",
             "Register new users instantly, or require confirmation via\n"
             "email?"),
         (BooleanOption, "email_registration_confirmation", "yes",
-            "Offer registration confirmation by email or only through the web?"),
+            "Offer registration confirmation by email or only\n"
+            "through the web?"),
         (IndexerOption, "indexer", "",
             "Force Roundup to use a particular text indexer.\n"
             "If no indexer is supplied, the first available indexer\n"
@@ -1108,8 +1110,8 @@ def str2value(self, value):
             "A descriptive name for your roundup instance."),
         (WebUrlOption, "web", NODEFAULT,
             "The web address that the tracker is viewable at.\n"
-            "This will be included in information"
-            " sent to users of the tracker.\n"
+            "This will be included in information\n"
+            "sent to users of the tracker.\n"
             "The URL MUST include the cgi-bin part or anything else\n"
             "that is required to get to the home page of the tracker.\n"
             "URL MUST start with http/https scheme and end with '/'"),
@@ -1216,24 +1218,26 @@ def str2value(self, value):
 email)."""),
         (BooleanOption, 'enable_xmlrpc', "yes",
             """Whether to enable the XMLRPC API in the roundup web
-interface. By default the XMLRPC endpoint is the string 'xmlrpc'
-after the roundup web url configured in the 'tracker' section.
-If this variable is set to 'no', the xmlrpc path has no special meaning
-and will yield an error message."""),
+interface. By default the XMLRPC endpoint is the string
+'xmlrpc' after the roundup web url configured in the
+'tracker' section. If this variable is set to 'no', the
+xmlrpc path has no special meaning and will yield an
+error message."""),
         (BooleanOption, 'translate_xmlrpc', 'no',
             """Whether to enable i18n for the xmlrpc endpoint. Enable it if
-you want to enable translation based on browsers lang (if enabled), trackers
-lang (if set) or environment."""),
+you want to enable translation based on browsers lang
+(if enabled), trackers lang (if set) or environment."""),
         (BooleanOption, 'enable_rest', "yes",
             """Whether to enable the REST API in the roundup web
-interface. By default the REST endpoint is the string 'rest' plus any
-additional REST-API parameters after the roundup web url configured in
-the tracker section. If this variable is set to 'no', the rest path has
-no special meaning and will yield an error message."""),
+interface. By default the REST endpoint is the string
+'rest' plus any additional REST-API parameters after the
+roundup web url configured in the tracker section. If this
+variable is set to 'no', the rest path has no special meaning
+and will yield an error message."""),
         (BooleanOption, 'translate_rest', 'no',
             """Whether to enable i18n for the rest endpoint. Enable it if
-you want to enable translation based on browsers lang (if enabled), trackers
-lang (if set) or environment."""),
+you want to enable translation based on browsers lang
+(if enabled), trackers lang (if set) or environment."""),
         (IntegerNumberGeqZeroOption, 'api_calls_per_interval', "0",
          "Limit API calls per api_interval_in_sec seconds to\n"
          "this number.\n"
@@ -1370,8 +1374,9 @@ def str2value(self, value):
             "in the user's browser rather than emailing them to the\n"
             "tracker admin."),
         (BooleanOption, "login_empty_passwords", "no",
-            "Setting this option to yes/true allows users with an empty/blank\n"
-            "password to login to the web/http interfaces."),
+            "Setting this option to yes/true allows users with\n"
+            "an empty/blank password to login to the\n"
+            "web/http interfaces."),
         (BooleanOption, "migrate_passwords", "yes",
             "Setting this option makes Roundup migrate passwords with\n"
             "an insecure password-scheme to a more secure scheme\n"
@@ -1436,11 +1441,14 @@ def str2value(self, value):
         (IntegerNumberGeqZeroOption, 'cache_size', '100',
             "Size of the node cache (in elements)"),
         (BooleanOption, "allow_create", "yes",
-            "Setting this option to 'no' protects the database against table creations."),
+            "Setting this option to 'no' protects the database against\n"
+            "table creations."),
         (BooleanOption, "allow_alter", "yes",
-            "Setting this option to 'no' protects the database against table alterations."),
+            "Setting this option to 'no' protects the database against\n"
+            "table alterations."),
         (BooleanOption, "allow_drop", "yes",
-            "Setting this option to 'no' protects the database against table drops."),
+            "Setting this option to 'no' protects the database against\n"
+            "table drops."),
         (NullableOption, 'template', '',
             "Name of the PostgreSQL template for database creation.\n"
             "For database creation the template used has to match\n"
@@ -1461,7 +1469,7 @@ def str2value(self, value):
             "Set the database cursor for filter queries to serverside\n"
             "cursor, this avoids caching large amounts of data in the\n"
             "client. This option only applies for the postgresql backend."),
-    ), "Settings in this section (except for backend) are used"
+    ), "Settings in this section (except for backend) are used\n"
         " by RDBMS backends only."
     ),
     ("sessiondb", (
@@ -1538,14 +1546,14 @@ def str2value(self, value):
         (FilePathOption, "debug", "",
             "Setting this option makes Roundup write all outgoing email\n"
             "messages to this file *instead* of sending them.\n"
-            "This option has the same effect as environment variable"
-            " SENDMAILDEBUG.\nEnvironment variable takes precedence."),
+            "This option has the same effect as the environment variable\n"
+            "SENDMAILDEBUG.\nEnvironment variable takes precedence."),
         (BooleanOption, "add_authorinfo", "yes",
             "Add a line with author information at top of all messages\n"
             "sent by roundup"),
         (BooleanOption, "add_authoremail", "yes",
-            "Add the mail address of the author to the author information at\n"
-            "the top of all messages.\n"
+            "Add the mail address of the author to the author information\n"
+            "at the top of all messages.\n"
             "If this is false but add_authorinfo is true, only the name\n"
             "of the actor is added which protects the mail address of the\n"
             "actor from being exposed at mail archives, etc."),

website/www/conf.py

@@ -74,6 +74,7 @@
                     'docs/whatsnew-0.7.txt',
                     'docs/whatsnew-0.8.txt',
                     'robots.txt',
+                    'docs/tracker_config.txt',
                     '_tmp']
 
 # The reST default role (used for this markup: `text`) to use for all documents.