From fc748eb3d06db5fd6d72c7b1f9247fe9c05b900e Mon Sep 17 00:00:00 2001 From: Todd Gamblin Date: Tue, 30 Aug 2016 11:28:17 -0700 Subject: 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. --- lib/spack/docs/conf.py | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) 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. -- cgit v1.2.3-60-g2f50