site_scons/epydoc.py

   1 # SPDX-License-Identifier: MIT
   2 #
   3 # Copyright The SCons Foundation
   4
   5 """
   6 Setup epydoc builder
   7
   8 Obsolete: epydoc no longer maintained.
   9 """
  10
  11 from SCons.Script import Delete, Touch, WhereIs
  12
  13 epydoc_cli = WhereIs('epydoc')
  14
  15 if not epydoc_cli:
  16     try:
  17         import epydoc
  18     except ImportError:
  19         epydoc = None
  20     else:
  21         # adding Epydoc builder using imported module
  22         def epydoc_builder_action(target, source, env):
  23             """
  24             Take a list of `source` files and build docs for them in
  25             `target` dir.
  26
  27             `target` and `source` are lists.
  28
  29             Uses OUTDIR and EPYDOCFLAGS environment variables.
  30
  31             http://www.scons.org/doc/2.0.1/HTML/scons-user/x3594.html
  32             """
  33
  34             # the epydoc build process is the following:
  35             # 1. build documentation index
  36             # 2. feed doc index to writer for docs
  37
  38             from epydoc.docbuilder import build_doc_index
  39             from epydoc.docwriter.html import HTMLWriter
  40             # from epydoc.docwriter.latex import LatexWriter
  41
  42             # first arg is a list where can be names of python package dirs,
  43             # python files, object names or objects itself
  44             docindex = build_doc_index([str(src) for src in source])
  45             if docindex is None:
  46                 return -1
  47
  48             if env['EPYDOCFLAGS'] == '--html':
  49                 html_writer = HTMLWriter(docindex,
  50                                          docformat='restructuredText',
  51                                          prj_name='SCons',
  52                                          prj_url='http://www.scons.org/')
  53                 try:
  54                     html_writer.write(env['OUTDIR'])
  55                 except OSError: # If directory cannot be created or any file cannot
  56                                 # be created or written to.
  57                     return -2
  58
  59             """
  60             # PDF support requires external Linux utilites, so it's not crossplatform.
  61             # Leaving for now.
  62             # http://epydoc.svn.sourceforge.net/viewvc/epydoc/trunk/epydoc/src/epydoc/cli.py
  63
  64             elif env['EPYDOCFLAGS'] == '--pdf':
  65                 pdf_writer = LatexWriter(docindex,
  66                                          docformat='restructuredText',
  67                                          prj_name='SCons',
  68                                          prj_url='http://www.scons.org/')
  69             """
  70             return 0
  71
  72         epydoc_commands = [
  73             Delete('$OUTDIR'),
  74             epydoc_builder_action,
  75             Touch('$TARGET'),
  76         ]
  77
  78 else:
  79     # epydoc_cli is found
  80     epydoc_commands = [
  81         Delete('$OUTDIR'),
  82         '$EPYDOC $EPYDOCFLAGS --debug --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES',
  83         Touch('$TARGET'),
  84     ]