Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-17831

Convert sconsUtils to sphinx documentation

    Details

    • Templates:
    • 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

          Container Issues

            Activity

              People

              • Assignee:
                tjenness Tim Jenness
                Reporter:
                tjenness Tim Jenness
                Reviewers:
                Kian-Tat Lim
                Watchers:
                Jim Bosch, John Swinbank, Jonathan Sick, Kian-Tat Lim, Tim Jenness
              • Votes:
                0 Vote for this issue
                Watchers:
                5 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Summary Panel