Merge lp:~javier.collado/utah/docs_html_build_errors into lp:utah

[Javier Collado]

The configuration file `conf.py` tries to generate the contents for the man
pages only when they are going to be built. However, it seems that trying to
generate the html documentation without those files results in lots errors
being printed. To fix that, the files for the man pages are generated for all
cases.

[Max Brustkern (nuclearbob)]

So is the change here just removing these lines:
# Note: This assumes that sphinx-build is called as in the makefile like this:
# /usr/bin/sphinx-build -b man <sphinx_opts>
if sys.argv[2] == 'man':
Adding the extra blank line, and unindenting everything? If so, that makes sense to me.

[Javier Collado (javier.collado)]

@Max

Yes, that's the only thing it does.

=== modified file 'docs/source/conf.py'
--- docs/source/conf.py	2012-09-14 11:11:38 +0000
+++ docs/source/conf.py	2012-10-18 15:17:19 +0000
@@ -67,76 +67,74 @@
                  'apt', 'apt.cache'):
     sys.modules[mod_name] = ModuleMock(mod_name)
 
+
 # Autogenerate help contents for manual pages when building manual pages
-# Note: This assumes that sphinx-build is called as in the makefile like this:
-# /usr/bin/sphinx-build -b man <sphinx_opts>
-if sys.argv[2] == 'man':
-    def get_parser_strings(script_name, parser):
-        description = parser.description
-
-        help_lines = parser.format_help().splitlines()
-        options_lines = itertools.dropwhile(
-                lambda l: l != 'optional arguments:',
-                help_lines)  # Drop usage
-        options_lines = itertools.takewhile(
-                lambda l: bool(l),
-                options_lines)  # Drop epilog
-        options_lines.next()  # Drop first line
-
-        def fix_line(line):
-            """
-            Remove indentation and replace curly braces with angle brackets
-            to match the expected format
-            """
-            line = line[2:]
-
-            # Apply changes only to option lines,
-            # not the ones with the help text
-            if line.startswith('-'):
-                line = line.replace('{', '<')
-                line = line.replace('}', '>')
-            return line
-
-        options_lines = [fix_line(line) for line in options_lines]
-        options = '\n'.join(options_lines)
-
-        if parser.epilog is None:
-            epilog = ''
-        else:
-            # Highlight program name and options
-            epilog = parser.epilog % {'prog': '**%s**' % script_name}
-            epilog = re.sub(r'(-\w)', r'**\1**', epilog)
-
-            # Duplicate backslashes to avoid dropping them
-            # because of the rst formatting
-            epilog = re.sub(r'\\', r'\\\\', epilog)
-
-            # Drop 'For example:'
-            epilog = '\n'.join(epilog.splitlines()[1:])
-
-            # Use line blocks to preserve line breaks
-            # Make sure that block is in a separate paragraph
-            epilog = re.sub(r'^\t', '\n| ', epilog, flags=re.M, count=1)
-            epilog = re.sub(r'^\t', '| ', epilog, flags=re.M)
-
-        return description, options, epilog
-
-    module_names = ('client', 'run_install_test', 'run_test_cobbler',
-                    'run_test_vm', 'run_utah_tests')
-    for module_name in module_names:
-        module = __import__(module_name)
-        parser = module.get_parser()
-        if module_name == 'client':
-            script_name = 'utah'
-        else:
-            script_name = '{}.py'.format(module_name)
-        description, options, epilog = get_parser_strings(script_name, parser)
-
-        for section_name in ('description', 'options', 'epilog'):
-            section = locals()[section_name]
-            filename = 'man/{}_{}.txt'.format(module_name, section_name)
-            with open(filename, 'w') as f:
-                f.write(section)
+def get_parser_strings(script_name, parser):
+    description = parser.description
+
+    help_lines = parser.format_help().splitlines()
+    options_lines = itertools.dropwhile(
+            lambda l: l != 'optional arguments:',
+            help_lines)  # Drop usage
+    options_lines = itertools.takewhile(
+            lambda l: bool(l),
+            options_lines)  # Drop epilog
+    options_lines.next()  # Drop first line
+
+    def fix_line(line):
+        """
+        Remove indentation and replace curly braces with angle brackets
+        to match the expected format
+        """
+        line = line[2:]
+
+        # Apply changes only to option lines,
+        # not the ones with the help text
+        if line.startswith('-'):
+            line = line.replace('{', '<')
+            line = line.replace('}', '>')
+        return line
+
+    options_lines = [fix_line(line) for line in options_lines]
+    options = '\n'.join(options_lines)
+
+    if parser.epilog is None:
+        epilog = ''
+    else:
+        # Highlight program name and options
+        epilog = parser.epilog % {'prog': '**%s**' % script_name}
+        epilog = re.sub(r'(-\w)', r'**\1**', epilog)
+
+        # Duplicate backslashes to avoid dropping them
+        # because of the rst formatting
+        epilog = re.sub(r'\\', r'\\\\', epilog)
+
+        # Drop 'For example:'
+        epilog = '\n'.join(epilog.splitlines()[1:])
+
+        # Use line blocks to preserve line breaks
+        # Make sure that block is in a separate paragraph
+        epilog = re.sub(r'^\t', '\n| ', epilog, flags=re.M, count=1)
+        epilog = re.sub(r'^\t', '| ', epilog, flags=re.M)
+
+    return description, options, epilog
+
+module_names = ('client', 'run_install_test', 'run_test_cobbler',
+                'run_test_vm', 'run_utah_tests')
+for module_name in module_names:
+    module = __import__(module_name)
+    parser = module.get_parser()
+    if module_name == 'client':
+        script_name = 'utah'
+    else:
+        script_name = '{}.py'.format(module_name)
+    description, options, epilog = get_parser_strings(script_name, parser)
+
+    for section_name in ('description', 'options', 'epilog'):
+        section = locals()[section_name]
+        filename = 'man/{}_{}.txt'.format(module_name, section_name)
+        with open(filename, 'w') as f:
+            f.write(section)
 
 # -- General configuration ----------------------------------------------------