#!/usr/bin/env python
"""Builds different documentation formats from docbook src

Here's the basic approach:
	A driver file defines system entities point to source-files
		(manual.xml)
	On reading the driver file, the parser pulls together all
	of the source-files into one big document.

	For the reference-manual, we merge in Python-specific
	annotations from a seperate directory tree with a (slow)
	merge.xsl template.

	Once we have the merged file, we can use the docbook-xsl
	templates to generate html, htmlhelp, or xhtml documents.
	Apparently we can also use latex/pdflatex if we have them
	to process this docbook file.

	For HTML files, we run David Carlisle' mathml XSL
	stylesheets in stand-alone mode to create IE-compatible
	HTML (with Javascript).

Note:
	This process is slow, even with Saxon (which is fairly
	fast).  It's untenably slow with the 4Suite XSLT package.

XXX Plans/desires:

	Eventually, I want to break the processing up into multiple
	distutils commands to allow for explicitly specifying which
	commands should be run, rather than having a single channel
	which decides which parts of itself to run:

		doc_merge_python -- merge individual sections with python
			annotations into combined document fragments
		doc_collect -- collect all individual section document
			fragments into a single large manual document
		doc_merge_samples -- add sample sections to the manual
		doc_build_xhtml -- use docbook-xsl to generate xHTML files
		doc_build_html -- convert xhtml to html
			doc_convert_mathml -- process html to make the html files
				work under IE 5 and 6
		doc_build_htmlhelp -- use docbook-xsl to generate HTMLHelp
			files
			doc_convert_mathml -- process html to make the html files
				work under IE 5 and 6

	and make the individual stages capable of optimizing in
	such a way that changing a particular python-specific
	document will only require merging that particular document
	and integrating it into the already-built manual, then
	running the appropriate doc_build_XXX commands. This will
	require completely rewriting the merge.xsl style sheet,
	and the driver code for manipulating it, as well as the
	build directory structure for holding the temporary files.

	I would also like to parameterize most of the functions
	so that we can generate/process the manual in non-standard
	places (to allow for, for instance, a special doc_build_html
	run which uses doc_merge_samples to not overwrite the
	standard manual).

	Should also eliminate the practice of directly writing to the
	OpenGL/doc directory during building, as this will cause
	problems if later build procedures fail.  Should generate the
	documents entirely within the build tree, and only copy them on
	complete success.
"""
import sys, os, os.path, re, string
from distutils.filelist import FileList
from distutils.errors import *
from util import *
import distutils.cmd
import glob, shutil

def show_formats ():
	"""Print all possible values for the 'formats' option (used by
	the "--help-formats" command-line option).
	"""
	from distutils.fancy_getopt import FancyGetopt
	formats=['html', 'xhtml', 'htmlhelp']
	formats.sort()
#	pretty_printer = FancyGetopt(formats)
#	pretty_printer.print_help(
#		"List of available source distribution formats:")


code_re = re.compile('&#([0-9]+);')

MATHPLAYER_BOILERPLATE = """
<object id="MathPlayer" classid="clsid:32F66A20-7614-11D4-BD11-00104BD3F987"></object>
<?import namespace="mml" IMPLEMENTATION="#MathPlayer" ?>
"""

CUSTOM_XSL = os.path.join("doc","xsl","html")
DOCBOOK_XSL_HOME = os.path.join("doc","docbook-xsl")
DOCBOOK_DTD_HOME = os.path.join("doc","docbook")
MATHML_CSS_HOME = os.path.join("doc","xsl","mathml")


class build_doc(distutils.cmd.Command):
	"""Build HTML/XHTML documentation for PyOpenGL"""
	description = '"build" documentation.'

	user_options = [
		('force', 'f', "forcibly build everything (ignore file timestamps)"),
		('formats=', None, 'Formats for documentation'),
		('kaffe', 'k', 'Use Kaffe instead of Java'),
		]

	boolean_options = ['force']

	help_options = [
		(
			'help-formats', None,
			'list available distribution formats', show_formats
		),
	]
	def initialize_options (self):
		self.force = None
		self.formats = None
		self.kaffe = None
	def finalize_options (self):
		self.set_undefined_options('build', ('force', 'force'))
		self.ensure_string_list('formats')
		if self.formats is None:
			self.formats = ['html']
		if 'all' in self.formats:
			self.formats = ['html', 'xhtml', 'web', 'htmlhelp']
		if self.kaffe:
			self.java = 'kaffe'
			self.acp = '-addclasspath'
		else:
			self.java = 'java'
			self.acp = '-cp'

	### Overall driver for process
	def run(self):
		"""The primary driver for the documentation-building system
		"""
		## Build our Java class-path value
		paths = []
		for (variable,jarName, packageName) in [
			("SAXON_HOME", "saxon.jar", "Saxon XSL Processor"),
			("RESOLVER_HOME","resolver.jar", "Sun Resolver XML Package"),
		]:
			if not os.environ.has_key(variable):
				self.warn( """Could not find %(variable)s environmental variable.
Install %(packageName)s and set environmental variable %(variable)s to point
to the directory holding %(jarName)s.
Aborting documentation generation."""%locals() )
				return
			paths.append( os.path.join(os.environ[variable], jarName) )
		# Add the docbook-xsl extensions
		os.path.join(DOCBOOK_XSL_HOME, 'extensions', 'saxon643.jar')
		for path in paths:
			if not os.path.isfile( path ):
				self.warn( """The class-path value %s does not appear to be a valid file, errors may result.  Please check environmental variables."""%(path,) )
		# Following puts the CatalogManager.properties file on the
		# path, though that doesn't seem to actually help much in
		# reducing reliance on networked files :( 
		paths.append( DOCBOOK_DTD_HOME )
		self.cp = string.join( paths, os.pathsep )

		f = FileList()
		f.findall('doc')
		f.process_template_line('global-include *.xml')
		manualTemp = os.path.join('build', 'doc', 'manual.xml')
		self.make_file(
			f.files,
			manualTemp,
			self.merge_doc,
			(
				os.path.join('doc', 'manual', 'manual.xml'),
				manualTemp,
			),
			exec_msg = 'Merging manpages and Python-specific documentation',
			skip_msg = 'Manpages already merged with Python-specific documentation'
		)

		for format in self.formats:
			name = 'run_' + format
			if hasattr(self, name):
				self.announce( """Building format %s"""%( format,))
				getattr(self, name)()	
			else:
				self.announce( """No support available for format %s"""%( format,))

	### Pre-processing to generate the docbook document from which all formats are generated
	def merge_doc(self, source, destination, **arguments ):
		"""Merge reference document with Python-specific annotations"""
		arguments['output'] = destination
		arguments['PyOpenGL_version']= self.distribution.get_version()
		rValue = apply(
			self.saxon, (
				os.path.join('doc', 'xsl', 'merge.xsl'),
				source,
			),
			arguments
		)
		# copy so that we have a backup if the later processing
		# mucks up the merged document...
		self.copy_file(destination, os.path.join('OpenGL','doc'))
		return rValue

	### Format-specific drivers
	def run_html(self):
		"""Top-level command for generating HTML documentation"""
		self.build_xhtml('.html', os.path.join('OpenGL','doc','html'), self.fix_html_mathmlcss)


	def run_xhtml(self):
		"""Top-level command for generating XHTML documentation"""
		self.build_xhtml('.xml', os.path.join('OpenGL','doc','xhtml'), self.fix_xhtml_ns)


	def gen_xhtml(self, ext, base_dir):
		"""Generate xhtml documentation to base_dir with file extensions ext"""
		try:
			self.saxon(
				os.path.join('doc', 'xsl', 'html', 'xhtml_chunk.xsl'),
				os.path.join('build', 'doc', 'manual.xml'),
				base_dir = base_dir + '/',
				html_ext = ext
			)
		except:
			self.rmtree(base_dir)
			raise


	def build_xhtml(self, ext, base_dir, cleanupFunction=None):
		"""Build an xhtml documentation set, running cleanupFunction afterward"""
		self.make_file(
			[os.path.join('build','doc','manual.xml')],
			os.path.join(base_dir , 'index' + ext),
			self.gen_xhtml,
			(ext, base_dir)
		)
		if cleanupFunction:
			cleanupFunction(
				os.path.join( base_dir, '*' + ext )
			)
	def copy_misc( self, base_dir ):
		"""Copy miscellaneous formatting files to a base_dir"""
		self.copy_file(os.path.join('doc','misc','style.css'), base_dir)
		self.copy_file(os.path.join('doc','misc','greypinstripe.png'), base_dir)

	def run_htmlhelp(self):
		"""Generate MS HTMLHelp documentation"""
		self.make_file(['build/doc/manual.xml'],
		               'build/doc/htmlhelp/index.html',
		               self.gen_html,
		               ('build/doc/htmlhelp', 'build/doc/htmlhelp', 'htmlhelp.xsl'))

		self.mkpath('build/doc/htmlhelp')

		for file in ('manual.hhp', 'manual.hhc'):
			if os.path.exists(file):
				x = open(file).read()
##				x = string.replace(x, 'build/doc/htmlhelp_raw/', '')
				x = string.replace(x, 'build/doc/htmlhelp/', '')
				open(os.path.join('build', 'doc', 'htmlhelp', file), 'w').write(x)
				os.remove(file)
			
#		self.move_file('manual.hhp', 'build/doc/htmlhelp')
#		self.move_file('toc.hhc', 'build/doc/htmlhelp')
		
##		self.make_file(['build/doc/htmlhelp_raw/index.html'],
##		               'build/doc/htmlhelp/index.html',
##		               self.xform_html,
##		               ('build/doc/htmlhelp_raw', 'build/doc/htmlhelp'))

		self.copy_file('doc/misc/style.css', 'build/doc/htmlhelp')
		self.copy_file('doc/misc/greypinstripe.png', 'build/doc/htmlhelp')
	
		f = FileList()
		f.findall('build/doc/htmlhelp')
		f.process_template_line('global-include *')
		self.make_file(f.files,
		               'build/doc/htmlhelp/manual.chm',
		               self.hhc,
		               ())

		self.copy_file('build/doc/htmlhelp/manual.chm', 'OpenGL/doc')

	def hhc(self):
		"""Spawn the HTMLHelp compiler"""
		try:
			self.spawn(['hhc', os.path.join('build', 'doc', 'htmlhelp', 'manual.hhp')])
		except DistutilsExecError, e:
			print e
			

	def pdflatex(self):
		for i in range(3):
			self.spawn(['pdflatex', '&pdfxmltex', 'manual.xml'])


	def latex(self):
		for i in range(3):
			self.spawn(['latex', '&xmltex', 'manual.xml'])


	### Utility functions
	def saxon(self, xsl, source, output = None, **params):
		"""Run the saxon XSL processor in our environment

		Most functions wind up working through this method
		one way or another.  Basically anything which uses
		XSL transformations will call this method
		"""
		saxon_cmd = [self.java,
		             self.acp,
		             self.cp,
		             'com.icl.saxon.StyleSheet',
		             '-x',
		             'com.sun.resolver.tools.ResolvingXMLReader',
		             '-y',
		             'com.sun.resolver.tools.ResolvingXMLReader',
		             '-r',
		             'com.sun.resolver.tools.CatalogResolver']
		if output is not None:
			saxon_cmd.extend(['-o', output])
		saxon_cmd.extend([source, xsl])
		for key, value in params.items():
			saxon_cmd.append('%s=%s' % (string.replace(key, '_', '.'), value))
		self.spawn(saxon_cmd)



	def fix_xhtml_ns(self, path):
		"""Minor postprocessing to add namespace declarations for xhtml compliance"""
		self.announce('Fixing XHTML namespace attribute: %s'%(path,))
		for i in glob.glob(path):
			if os.path.isfile(i):
				x = open(i).read()
				if string.count(x, '<html>'):
					x = string.replace(x, '<html>', """<html
	xmlns="http://www.w3.org/1999/xhtml"
	xmlns:mml="http://www.w3.org/1998/Math/MathML"
>""")
					open(i, 'w').write(x)
	def fix_html_mathmlcss( self, path ):
		"""Use the MathML XSL->CSS style sheet to convert xhtml->html"""
		self.announce('Doing xhtml->html+css conversion: %s'%(path,))
		requireExtra = []
		def target( filename ):
			"""Return .html version of filename"""
			return os.path.splitext( filename )[0]+ '.html'
		for i in glob.glob(path):
			if os.path.isfile(i):
				targetName = target( i )
				x = open(i).read()
				if x.find('mml:') > -1:
					requireExtra.append( (i, targetName) )
				x = string.replace(x, '<html>', """<html
xmlns:mml="http://www.w3.org/1998/Math/MathML"
>""")
##				if x.find('mml:') > -1:
##					x = finder.sub( r'%s</head'%(MATHPLAYER_BOILERPLATE), x )
				open(targetName, 'w').write(x)
		for filename, targetName in requireExtra:
			self._fix_html_mathmlcss( targetName, targetName )
	def _fix_html_mathmlcss( self, source, target ):
		"""Do single MathML->HTML+CSS conversion"""
		self.announce('MathML Render: %s'%(source, ))
		self.saxon(
			os.path.join(MATHML_CSS_HOME, 'pmathmlcss.xsl'),
			source,
			target,
		)

	def fix_html_mathplayer(self, path):
		"""Add IE+MathPlayer specific support to HTML files (obsolete)"""
		self.announce('Adding MathPlayer support to files: %s'%(path,))
		
		finder = re.compile( "\<\/head" )
		for i in glob.glob(path):
			if os.path.isfile(i):
				x = open(i).read()
				x = string.replace(x, '<html>', """<html
xmlns:mml="http://www.w3.org/1998/Math/MathML"
>""")
				if x.find('mml:') > -1:
					x = finder.sub( r'%s</head'%(MATHPLAYER_BOILERPLATE), x )
				open(i, 'w').write(x)

	def rmtree(self, dir):
		"""Forcibly recursively remove a directory tree

		Note: this isn't cross-platform at the moment...
		"""
		try:
			shutil.rmtree(apply(os.path.join, string.split(dir, '/')))
		except:
			pass