Details
-
Type:
Story
-
Status: Done
-
Resolution: Done
-
Fix Version/s: None
-
Component/s: pipelines_lsst_io, sconsUtils
-
Labels:None
-
Story Points:2
-
Sprint:Arch 2019-02-11
-
Team:Architecture
Description
Currently sconsUtils requires that doxygen strings be used to create the documentation. This is done because sconsUtils requires that SCons be imported and that is only possible if SCons is importing sconsUtils. Since pydoc and sphinx import python code to extract documentation this makes it hard to use numpydoc.
For example:
$ pydoc lsst.sconsUtils
|
problem in lsst.sconsUtils - ImportError: lsst.sconsUtils cannot be imported outside an scons script.
|
It seems though that this is easy to work around. The following patch allows pydoc to work and opens the possibility of migrating sconsUtils away from doxygen.
diff --git a/python/lsst/sconsUtils/__init__.py b/python/lsst/sconsUtils/__init__.py
|
index ee9f02a..6e3c456 100644
|
--- a/python/lsst/sconsUtils/__init__.py
|
+++ b/python/lsst/sconsUtils/__init__.py
|
@@ -1,4 +1,13 @@
|
# Explain what happens when you try to import outside scons
|
+# When building documentation you want to force a SCons import
|
+import os
|
+import sys
|
+
|
+if ("pydoc" in sys.modules or "sphinx" in sys.modules) and "SCONS_DIR" in os.environ:
|
+ scons_path = os.path.join(os.environ["SCONS_DIR"], "lib", "scons")
|
+ if scons_path not in sys.path:
|
+ sys.path.append(scons_path)
|
+
|
try:
|
import SCons.Script
|
except ImportError: |
Attachments
Activity
The scope was meant to be to update the sconsUtils docstrings and integrate into Sphinx (which I've done because I was clearly bored over the weekend).
My proposed patch does allow Sphinx to build the documentation. I have ported all the doxygen to numpydoc (some of it was already numpydoc) and added a sphinx build. There is one remaining problem in that all the methods that are inserted into SConsEnvironment at import time are not picked up by Sphinx and it complains that they are not part of the toctree. Maybe it would work to create a dummy class that inherits from SConsEnvironment.
Brilliant! I like it. Shall we add this to the pipelines_lsst_io table file?
Looked through most of it, but with a pretty coarse comb that might have missed some stuff. It looks like a definite improvement.
Thanks for the reviews. Merged. Jonathan Sick feel free to add to pipelines.lsst.io.
Tim Jenness — can you clarify the scope of this ticket, please? Is it supposed to mean “somebody should apply the provided patch”, or “after this patch has been applied (on another ticket?) somebody should edit some docstrings”?