summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTodd Gamblin <tgamblin@llnl.gov>2016-08-30 11:28:17 -0700
committerAdam J. Stewart <ajstewart426@gmail.com>2016-08-30 16:36:50 -0500
commitfc748eb3d06db5fd6d72c7b1f9247fe9c05b900e (patch)
tree6c605c938f61503488c7a02cca4390767a13dd83
parent1be6267149ba2fdd3d510bde713b237eaa0248e9 (diff)
downloadspack-fc748eb3d06db5fd6d72c7b1f9247fe9c05b900e.tar.gz
spack-fc748eb3d06db5fd6d72c7b1f9247fe9c05b900e.tar.bz2
spack-fc748eb3d06db5fd6d72c7b1f9247fe9c05b900e.tar.xz
spack-fc748eb3d06db5fd6d72c7b1f9247fe9c05b900e.zip
Exclude spack.__all__ from documentation.
Everything in the __all__ list in the spack module is from some other module, so only do their documentation in their original location. This also avoids issues like the fact that some directive names shadow spack core module names.
-rw-r--r--lib/spack/docs/conf.py22
1 files changed, 22 insertions, 0 deletions
diff --git a/lib/spack/docs/conf.py b/lib/spack/docs/conf.py
index 1416074356..a702e70e51 100644
--- a/lib/spack/docs/conf.py
+++ b/lib/spack/docs/conf.py
@@ -47,6 +47,7 @@ from glob import glob
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('exts'))
sys.path.insert(0, os.path.abspath('../external'))
+sys.path.append(os.path.abspath('../spack'))
# Add the Spack bin directory to the path so that we can use its output in docs.
spack_root = '../../..'
@@ -82,6 +83,27 @@ with open('command_index.rst', 'a') as index:
for cmd in command_names:
index.write(' * :ref:`%s`\n' % cmd)
+#
+# Exclude everything in spack.__all__ from indexing. All of these
+# symbols are imported from elsewhere in spack; their inclusion in
+# __all__ simply allows package authors to use `from spack import *`.
+# Excluding them ensures they're only documented in their "real" module.
+#
+# This also avoids issues where some of these symbols shadow core spack
+# modules. Sphinx will complain about duplicate docs when this happens.
+#
+import fileinput, spack
+handling_spack = False
+for line in fileinput.input('spack.rst', inplace=1):
+ if handling_spack:
+ if not line.startswith(' :noindex:'):
+ print ' :noindex: %s' % ' '.join(spack.__all__)
+ handling_spack = False
+
+ if line.startswith('.. automodule::'):
+ handling_spack = (line == '.. automodule:: spack\n')
+
+ print line,
# Set an environment variable so that colify will print output like it would to
# a terminal.