Repository: spack/spack

Issue:
Can't make documentation without running make clean first
If you run `make` twice in the documentation directory without running `make clean` in-between, you see strange warning messages:

```
/Users/Adam/spack/lib/spack/docs/index.rst:44: WARNING: toctree contains reference to document u'package_list' that doesn't have a title: no link will be generated
/Users/Adam/spack/lib/spack/docs/index.rst:44: WARNING: toctree contains reference to document u'package_list' that doesn't have a title: no link will be generated
/Users/Adam/spack/lib/spack/docs/index.rst:44: WARNING: toctree contains reference to document u'package_list' that doesn't have a title: no link will be generated
/Users/Adam/spack/lib/spack/docs/index.rst:44: WARNING: toctree contains reference to document u'package_list' that doesn't have a title: no link will be generated
/Users/Adam/spack/lib/spack/docs/index.rst:44: WARNING: toctree contains reference to document u'package_list' that doesn't have a title: no link will be generated
generating indices... genindex/Users/Adam/spack/lib/spack/docs/index.rst:44: WARNING: toctree contains reference to document u'package_list' that doesn't have a title: no link will be generated
 py-modindex/Users/Adam/spack/lib/spack/docs/index.rst:44: WARNING: toctree contains reference to document u'package_list' that doesn't have a title: no link will be generated

writing additional pages... search/Users/Adam/spack/lib/spack/docs/index.rst:44: WARNING: toctree contains reference to document u'package_list' that doesn't have a title: no link will be generated
```

This warning message usually happens when you try to include a file without a title in the toctree, but package_list.rst does have a title, so I have no idea what's going on.



Discussion:
@tgamblin Can you add a label for "documentation"? I think it would be useful to mark issues and PR's that affect the documentation.

Assuming fixed by #1742

ok maybe i didn't look at this thoroughly enough

Unfortunately not. `run-doc-tests` is now fixed because it runs `make clean` first, but I assume it's a bug that running `make` twice in a row causes it to crash?


Resolving patch:
diff --git a/lib/spack/docs/conf.py b/lib/spack/docs/conf.py
--- a/lib/spack/docs/conf.py
+++ b/lib/spack/docs/conf.py
@@ -1,10 +1,7 @@
 # flake8: noqa
 ##############################################################################
-# Copyright (c) 2013, Lawrence Livermore National Security, LLC.
-# Produced at the Lawrence Livermore National Laboratory.
-#
 # This file is part of Spack.
-# Written by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# Created by Todd Gamblin, tgamblin@llnl.gov.
 # LLNL-CODE-647188
 #
 # For details, see https://github.com/llnl/spack
@@ -70,9 +67,10 @@
 #
 # Generate package list using spack command
 #
-with open('package_list.rst', 'w') as plist_file:
-    subprocess.Popen(
-        [spack_root + '/bin/spack', 'package-list'], stdout=plist_file)
+if not os.path.exists('package_list.rst'):
+    with open('package_list.rst', 'w') as plist_file:
+        subprocess.Popen(
+            [spack_root + '/bin/spack', 'package-list'], stdout=plist_file)
 
 #
 # Find all the `spack-*` references and add them to a command index
@@ -85,11 +83,12 @@
             if match:
                 command_names.append(match.group(1).strip())
 
-shutil.copy('command_index.in', 'command_index.rst')
-with open('command_index.rst', 'a') as index:
-    index.write('\n')
-    for cmd in sorted(command_names):
-        index.write('   * :ref:`%s`\n' % cmd)
+if not os.path.exists('command_index.rst'):
+    shutil.copy('command_index.in', 'command_index.rst')
+    with open('command_index.rst', 'a') as index:
+        index.write('\n')
+        for cmd in sorted(command_names):
+            index.write('   * :ref:`%s`\n' % cmd)
 
 
 # Run sphinx-apidoc


Test patch: