From 62fa838f6c3bababe376b75684d29c699f1fce31 Mon Sep 17 00:00:00 2001 From: gggeek Date: Mon, 27 Apr 2015 02:32:42 +0100 Subject: [PATCH] Add generation of docs to pakefile --- Makefile | 125 ----------------------------------- NEWS | 2 + composer.json | 3 +- doc/Makefile | 80 ---------------------- doc/convert.php | 61 ----------------- doc/custom.fo.xsl | 2 +- doc/highlight.php | 43 ------------ pakefile.php | 164 +++++++++++++++++++++++++++++++++++++++++++--- 8 files changed, 160 insertions(+), 320 deletions(-) delete mode 100644 Makefile delete mode 100644 doc/Makefile delete mode 100644 doc/convert.php delete mode 100644 doc/highlight.php diff --git a/Makefile b/Makefile deleted file mode 100644 index c6d4985..0000000 --- a/Makefile +++ /dev/null @@ -1,125 +0,0 @@ -# Makefile for phpxmlrpc library - -### USER EDITABLE VARS - can be passed as command-line options ### - -# path to PHP executable, preferably CLI version -PHP=php - -# path were xmlrpc lib files will be copied to -PHPINCLUDEDIR=/usr/local/lib/php - -# mkdir is a thorny beast under windows: make sure we can not use the cmd version, running eg. "make MKDIR=mkdir.exe" -MKDIR=mkdir - -#find too -FIND=find - -DOS2UNIX=dos2unix - -#### DO NOT TOUCH FROM HERE ONWARDS ### - -# recover version number from code -# thanks to Firman Pribadi for unix command line help -# on unix shells lasts char should be \\2/g ) -export VERSION=$(shell grep -E "\$GLOBALS *\[ *'xmlrpcVersion' *\] *= *'" lib/xmlrpc.inc | sed -r s/"(.*= *' *)([0-9a-zA-Z.-]+)(.*)"/\2/g ) - -LIBFILES=lib/xmlrpc.inc lib/xmlrpcs.inc lib/xmlrpc_wrappers.inc \ - src/*.php src/Helper/*.php - -EXTRAFILES=extras/test.pl \ - extras/test.py \ - extras/rsakey.pem \ - extras/workspace.testPhpServer.fttb - -DEMOFILES=demo/vardemo.php \ - demo/demo1.xml \ - demo/demo2.xml \ - demo/demo3.xml - -DEMOSFILES=demo/server/discuss.php \ - demo/server/server.php \ - demo/server/proxy.php - -DEMOCFILES=demo/client/agesort.php \ - demo/client/client.php \ - demo/client/comment.php \ - demo/client/introspect.php \ - demo/client/mail.php \ - demo/client/simple_call.php \ - demo/client/which.php \ - demo/client/wrap.php \ - demo/client/zopetest.php - -TESTFILES=test/testsuite.php \ - tests/benchmark.php \ - tests/parse_args.php \ - test/InvalidHostTest.php \ - test/LocalHostTest.php \ - test/ParsingBugsTest.php \ - tests/verify_compat.php - -INFOFILES=Changelog \ - Makefile \ - NEWS \ - README - -DEBUGGERFILES=debugger/index.php \ - debugger/action.php \ - debugger/common.php \ - debugger/controller.php - - -all: install - -install: - cp ${LIBFILES} ${PHPINCLUDEDIR} - @echo Lib files have been copied to ${PHPINCLUDEDIR} - cd doc && $(MAKE) install - -test: - cd test && ${PHP} -q testsuite.php - - -### the following targets are to be used for library development ### - -# make tag target: tag existing working copy as release in git. -tag: - git tag v${VERSION} - git push origin --tags - -dist: xmlrpc-${VERSION}.zip xmlrpc-${VERSION}.tar.gz - -xmlrpc-${VERSION}.zip xmlrpc-${VERSION}.tar.gz: ${LIBFILES} ${DEBUGGERFILES} ${INFOFILES} ${TESTFILES} ${EXTRAFILES} ${DEMOFILES} ${DEMOSFILES} ${DEMOCFILES} - @echo ---${VERSION}--- - rm -rf xmlrpc-${VERSION} - ${MKDIR} xmlrpc-${VERSION} - ${MKDIR} xmlrpc-${VERSION}/demo - ${MKDIR} xmlrpc-${VERSION}/demo/client - ${MKDIR} xmlrpc-${VERSION}/demo/server - ${MKDIR} xmlrpc-${VERSION}/test - ${MKDIR} xmlrpc-${VERSION}/test/PHPUnit - ${MKDIR} xmlrpc-${VERSION}/extras - ${MKDIR} xmlrpc-${VERSION}/lib - ${MKDIR} xmlrpc-${VERSION}/debugger - cp --parents ${DEMOFILES} xmlrpc-${VERSION} - cp --parents ${DEMOCFILES} xmlrpc-${VERSION} - cp --parents ${DEMOSFILES} xmlrpc-${VERSION} - cp --parents ${TESTFILES} xmlrpc-${VERSION} - cp --parents ${EXTRAFILES} xmlrpc-${VERSION} - cp --parents ${LIBFILES} xmlrpc-${VERSION} - cp --parents ${DEBUGGERFILES} xmlrpc-${VERSION} - cp ${INFOFILES} xmlrpc-${VERSION} - cd doc && $(MAKE) dist -# on unix shells last char should be \; - ${FIND} xmlrpc-${VERSION} -type f ! -name "*.fttb" ! -name "*.pdf" ! -name "*.gif" -exec ${DOS2UNIX} ; - -rm xmlrpc-${VERSION}.zip xmlrpc-${VERSION}.tar.gz - tar -cvf xmlrpc-${VERSION}.tar xmlrpc-${VERSION} - gzip xmlrpc-${VERSION}.tar - zip -r xmlrpc-${VERSION}.zip xmlrpc-${VERSION} - -doc: - cd doc && $(MAKE) doc - -clean: - rm -rf xmlrpc-${VERSION} xmlrpc-${VERSION}.zip xmlrpc-${VERSION}.tar.gz - cd doc && $(MAKE) clean diff --git a/NEWS b/NEWS index 5062473..bba59f7 100644 --- a/NEWS +++ b/NEWS @@ -62,6 +62,8 @@ PLEASE READ CAREFULLY THE NOTES BELOW to insure a smooth upgrade. - at debug level 1, curl communication info are not dumped to screen - at debug level 1, the tests echo payloads of failures; at debug level 2 all payloads +* improved: makefiles have been replaced with a php_based pakefile + XML-RPC for PHP version 3.0.0 - 2014/6/15 diff --git a/composer.json b/composer.json index 788aa99..8a6f29f 100644 --- a/composer.json +++ b/composer.json @@ -14,7 +14,8 @@ "codeclimate/php-test-reporter": "dev-master", "ext-curl": "*", "ext-mbstring": "*", - "indeyets/pake": "~1.99" + "indeyets/pake": "~1.99", + "phpdocumentor/phpdocumentor": "2.*" }, "suggest": { "ext-curl": "Needed for HTTPS and HTTP 1.1 support, NTLM Auth etc...", diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index 5a77386..0000000 --- a/doc/Makefile +++ /dev/null @@ -1,80 +0,0 @@ - -### USER EDITABLE VARS ### - -WEB=/var/www/xmlrpc/doc - -MKDIR=mkdir - -PHP=php - -FOP=fop - -PHPDOC=phpdoc - - -#### DO NOT TOUCH FROM HERE ONWARDS ### - -install: - ${MKDIR} -p ${WEB} - cp *.html ${WEB} - cp *.css ${WEB} - cp *.gif ${WEB} - @echo HTML version of the manual has been installed to ${WEB} - - -### the following targets are to be used for library development ### - -doc: out/index.html xmlrpc_php.pdf javadoc-out/index.html - -# tools currently used in building docs: php 5 with xsl extension, apache fop, phpdocumentor -# alternatives include doxygen, jade, saxon, xsltproc etc... - -out/index.html xmlrpc_php.pdf: xmlrpc_php.xml - -${MKDIR} out -# Jade cmd yet to be rebuilt, starting from xml file and putting output in ./out dir, e.g. -# jade -t xml -d custom.dsl xmlrpc_php.xml -# -# convertdoc command for xmlmind xxe editor -# convertdoc docb.toHTML xmlrpc_php.xml -u out -# -# saxon + xerces xml parser + saxon extensions + xslthl: adds a little syntax highligting -# (bold and italics only, no color) for php source examples... -# java \ -# -classpath c:\programmi\saxon\saxon.jar\;c:\programmi\saxon\xslthl.jar\;c:\programmi\xerces\xercesImpl.jar\;C:\htdocs\xmlrpc_cvs\docbook-xsl\extensions\saxon65.jar \ -# -Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl \ -# -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl \ -# -Dxslthl.config=file:///c:/htdocs/xmlrpc_cvs/docbook-xsl/highlighting/xslthl-config.xml \ -# com.icl.saxon.StyleSheet -o xmlrpc_php.fo.xml xmlrpc_php.xml custom.fo.xsl use.extensions=1 -# -# custom php script that does the xslt magic - ${PHP} convert.php xmlrpc_php.xml custom.xsl out/ -# post process html files to highlight php code samples - ${PHP} highlight.php out -# convert to fo and then to pdf using apache fop - ${PHP} convert.php xmlrpc_php.xml custom.fo.xsl xmlrpc_php.fo.xml - ${FOP} xmlrpc_php.fo.xml xmlrpc_php.pdf -# -rm xmlrpc_php.fo.xml - -javadoc-out/index.html: ../lib/xmlrpc.inc ../lib/xmlrpcs.inc ../lib/xmlrpc_wrappers.inc -# generate docs out of javadoc via doxygen -# doxygen phpxmlrpc.dox -# -# generate docs out of javadoc via phpdocumentor - ${PHP} ${PHPDOC} -f ../lib/xmlrpc.inc,../lib/xmlrpcs.inc,../lib/xmlrpc_wrappers.inc -t javadoc-out --title PHP-XMLRPC - -rm -rf javadoc-out/phpdoc-cache-* - -dist: doc - ${MKDIR} -p ../xmlrpc-${VERSION}/doc - -cp out/*.html ../xmlrpc-${VERSION}/doc - -cp out/*.css ../xmlrpc-${VERSION}/doc - -cp out/*.gif ../xmlrpc-${VERSION}/doc - -cp out/*.pdf ../xmlrpc-${VERSION}/doc - cp xmlrpc_php.xml ../xmlrpc-${VERSION}/doc - cp xmlrpc_php.pdf ../xmlrpc-${VERSION}/doc - cp Makefile ../xmlrpc-${VERSION}/doc - -clean: - -rm -f out/*.html - -rm -rf javadoc-out - -rm xmlrpc_php.fo.xml - -rm xmlrpc_php.pdf diff --git a/doc/convert.php b/doc/convert.php deleted file mode 100644 index a7e08cb..0000000 --- a/doc/convert.php +++ /dev/null @@ -1,61 +0,0 @@ -load($doc); -$xsl = new DOMDocument(); -$xsl->load($xss); - -// Configure the transformer -$proc = new XSLTProcessor(); -if (version_compare(PHP_VERSION, '5.4', "<")) { - if (defined('XSL_SECPREF_WRITE_FILE')) { - ini_set("xsl.security_prefs", XSL_SECPREF_CREATE_DIRECTORY | XSL_SECPREF_WRITE_FILE); - } -} else { - // the php online docs only mention setSecurityPrefs, but somehow some installs have setSecurityPreferences... - if (method_exists('XSLTProcessor', 'setSecurityPrefs')) { - $proc->setSecurityPrefs(XSL_SECPREF_CREATE_DIRECTORY | XSL_SECPREF_WRITE_FILE); - } else { - $proc->setSecurityPreferences(XSL_SECPREF_CREATE_DIRECTORY | XSL_SECPREF_WRITE_FILE); - } -} -$proc->importStyleSheet($xsl); // attach the xsl rules - -//if ($_SERVER['argc'] >= 4) -//{ -if (is_dir($_SERVER['argv'][3])) { - if (!$proc->setParameter('', 'base.dir', realpath($_SERVER['argv'][3]))) { - echo "setting param base.dir KO\n"; - } -} else { - //echo "{$_SERVER['argv'][3]} is not a dir\n"; -} -//} - -$out = $proc->transformToXML($xml); -if (!is_dir($_SERVER['argv'][3])) { - file_put_contents($_SERVER['argv'][3], $out); -} - -echo "OK\n"; diff --git a/doc/custom.fo.xsl b/doc/custom.fo.xsl index 1fe0dda..1ba937c 100644 --- a/doc/custom.fo.xsl +++ b/doc/custom.fo.xsl @@ -12,7 +12,7 @@ - + diff --git a/doc/highlight.php b/doc/highlight.php deleted file mode 100644 index 750261b..0000000 --- a/doc/highlight.php +++ /dev/null @@ -1,43 +0,0 @@ -'; - $endtag = ''; - - $content = file_get_contents($file); - $last = 0; - $out = ''; - while (($start = strpos($content, $starttag, $last)) !== false) { - $end = strpos($content, $endtag, $start); - $code = substr($content, $start + strlen($starttag), $end - $start - strlen($starttag)); - if ($code[strlen($code) - 1] == "\n") { - $code = substr($code, 0, -1); - } - - $code = str_replace(array('>', '<'), array('>', '<'), $code); - $code = highlight_string('<?php 
', '', $code); - - $out = $out . substr($content, $last, $start + strlen($starttag) - $last) . $code . $endtag; - $last = $end + strlen($endtag); - } - $out .= substr($content, $last, strlen($content)); - - return $out; -} - -$dir = $argv[1]; - -$files = scandir($dir); -foreach ($files as $file) { - if (substr($file, -5, 5) == '.html') { - $out = highlight($dir . '/' . $file); - file_put_contents($dir . '/' . $file, $out); - } -} diff --git a/pakefile.php b/pakefile.php index 2ae9e35..5b7386b 100644 --- a/pakefile.php +++ b/pakefile.php @@ -3,7 +3,8 @@ * Makefile for phpxmlrpc library. * To be used with the Pake tool: https://github.com/indeyets/pake/wiki * - * @todo allow user to specify location for zip command + * @copyright (c) 2015 G. Giunta + * * @todo allow user to specify release number and tag/branch to use */ @@ -11,9 +12,14 @@ namespace PhpXmlRpc { class Builder { - protected static $buildDir = 'build/'; + protected static $buildDir = 'build'; protected static $libVersion; protected static $sourceBranch = 'master'; + protected static $tools = array( + 'zip' => 'zip', + 'fop' => 'fop', + 'php' => 'php' + ); public static function libVersion() { @@ -27,13 +33,13 @@ class Builder public static function workspaceDir() { - return self::buildDir().'workspace'; + return self::buildDir().'/workspace'; } /// most likely things will break if this one is moved outside of BuildDir public static function distDir() { - return self::buildDir().'xmlrpc-'.self::libVersion(); + return self::buildDir().'/xmlrpc-'.self::libVersion(); } /// these will be generated in BuildDir @@ -59,7 +65,96 @@ class Builder if (count($args) > 1) self::$sourceBranch = $args[1]; - pake_echo('---'.self::$libVersion.'---'); + foreach (self::$tools as $name => $binary) { + if (isset($cliOpts[$name])) { + self::$tools[$name] = $cliOpts[$name]; + } + } + + //pake_echo('---'.self::$libVersion.'---'); + } + + public static function tool($name) + { + return self::$tools[$name]; + } + + /** + * @param string $inFile + * @param string $xssFile + * @param string $outFileOrDir + * @throws \Exception + */ + public static function applyXslt($inFile, $xssFile, $outFileOrDir) + { + + if (!file_exists($inFile)) { + throw new \Exception("File $inFile cannot be found"); + } + if (!file_exists($xssFile)) { + throw new \Exception("File $xssFile cannot be found"); + } + + // Load the XML source + $xml = new \DOMDocument(); + $xml->load($inFile); + $xsl = new \DOMDocument(); + $xsl->load($xssFile); + + // Configure the transformer + $processor = new \XSLTProcessor(); + if (version_compare(PHP_VERSION, '5.4', "<")) { + if (defined('XSL_SECPREF_WRITE_FILE')) { + ini_set("xsl.security_prefs", XSL_SECPREF_CREATE_DIRECTORY | XSL_SECPREF_WRITE_FILE); + } + } else { + // the php online docs only mention setSecurityPrefs, but somehow some installs have setSecurityPreferences... + if (method_exists('XSLTProcessor', 'setSecurityPrefs')) { + $processor->setSecurityPrefs(XSL_SECPREF_CREATE_DIRECTORY | XSL_SECPREF_WRITE_FILE); + } else { + $processor->setSecurityPreferences(XSL_SECPREF_CREATE_DIRECTORY | XSL_SECPREF_WRITE_FILE); + } + } + $processor->importStyleSheet($xsl); // attach the xsl rules + + if (is_dir($outFileOrDir)) { + if (!$processor->setParameter('', 'base.dir', realpath($outFileOrDir))) { + echo "setting param base.dir KO\n"; + } + } + + $out = $processor->transformToXML($xml); + + if (!is_dir($outFileOrDir)) { + file_put_contents($outFileOrDir, $out); + } + } + + public static function highlightPhpInHtml($content) + { + $startTag = '
';
+        $endTag = '
'; + + //$content = file_get_contents($inFile); + $last = 0; + $out = ''; + while (($start = strpos($content, $startTag, $last)) !== false) { + $end = strpos($content, $endTag, $start); + $code = substr($content, $start + strlen($startTag), $end - $start - strlen($startTag)); + if ($code[strlen($code) - 1] == "\n") { + $code = substr($code, 0, -1); + } + + $code = str_replace(array('>', '<'), array('>', '<'), $code); + $code = highlight_string('<?php 
', '', $code); + + $out = $out . substr($content, $last, $start + strlen($startTag) - $last) . $code . $endTag; + $last = $end + strlen($endTag); + } + $out .= substr($content, $last, strlen($content)); + + return $out; } } @@ -71,10 +166,14 @@ use PhpXmlRpc\Builder; function run_default($task=null, $args=array(), $cliOpts=array()) { - echo "Syntax: pake {\$pake-options} \$task \$lib-version [\$git-tag]\n"; + echo "Syntax: pake {\$pake-options} \$task \$lib-version [\$git-tag] {\$task-options}\n"; echo "\n"; echo " Run 'pake help' to list all pake options\n"; echo " Run 'pake -T' to list all available tasks\n"; + echo " Task options:\n"; + echo " --php=\$php"; + echo " --fop=\$fop"; + echo " --zip=\$zip"; } function run_getopts($task=null, $args=array(), $cliOpts=array()) @@ -118,12 +217,56 @@ function run_build($task=null, $args=array(), $cliOpts=array()) { } +function run_clean_doc() +{ + pake_remove_dir(Builder::workspaceDir().'/doc/out'); + pake_remove_dir(Builder::workspaceDir().'/doc/javadoc-out'); +} + /** * Generates documentation in all formats */ function run_doc($task=null, $args=array(), $cliOpts=array()) { - pake_echo('TBD...'); + $docDir = Builder::workspaceDir().'/doc'; + + // API docs from phpdoc comments using phpdocumentor + $cmd = Builder::tool('php'); + pake_sh("$cmd vendor/phpdocumentor/phpdocumentor/bin/phpdoc run -d ".Builder::workspaceDir().'/src'." -t ".Builder::workspaceDir().'/doc/javadoc-out --title PHP-XMLRPC'); + + # Jade cmd yet to be rebuilt, starting from xml file and putting output in ./out dir, e.g. + # jade -t xml -d custom.dsl xmlrpc_php.xml + # + # convertdoc command for xmlmind xxe editor + # convertdoc docb.toHTML xmlrpc_php.xml -u out + # + # saxon + xerces xml parser + saxon extensions + xslthl: adds a little syntax highligting + # (bold and italics only, no color) for php source examples... + # java \ + # -classpath c:\programmi\saxon\saxon.jar\;c:\programmi\saxon\xslthl.jar\;c:\programmi\xerces\xercesImpl.jar\;C:\htdocs\xmlrpc_cvs\docbook-xsl\extensions\saxon65.jar \ + # -Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl \ + # -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl \ + # -Dxslthl.config=file:///c:/htdocs/xmlrpc_cvs/docbook-xsl/highlighting/xslthl-config.xml \ + # com.icl.saxon.StyleSheet -o xmlrpc_php.fo.xml xmlrpc_php.xml custom.fo.xsl use.extensions=1 + + pake_mkdirs($docDir.'/out'); + + // HTML files from docbook + + Builder::applyXslt($docDir.'/xmlrpc_php.xml', $docDir.'/custom.xsl', $docDir.'/out/'); + // post process html files to highlight php code samples + foreach(pakeFinder::type('file')->name('*.html')->in($docDir) as $file) + { + file_put_contents($file, Builder::highlightPhpInHtml(file_get_contents($file))); + } + + // PDF file from docbook + + // convert to fo and then to pdf using apache fop + Builder::applyXslt($docDir.'/xmlrpc_php.xml', $docDir.'/custom.fo.xsl', $docDir.'/xmlrpc_php.fo.xml'); + $cmd = Builder::tool('fop'); + pake_sh("$cmd $docDir/xmlrpc_php.fo.xml $docDir/xmlrpc_php.pdf"); + unlink($docDir.'/xmlrpc_php.fo.xml'); } function run_clean_dist() @@ -148,11 +291,12 @@ function run_dist($task=null, $args=array(), $cliOpts=array()) // also: do we still need to run dos2unix? // create tarballs + $cwd = getcwd(); chdir(dirname(Builder::distDir())); foreach(Builder::distFiles() as $distFile) { // php can not really create good zip files via phar: they are not compressed! if (substr($distFile, -4) == '.zip') { - $cmd = 'zip'; + $cmd = Builder::tool('zip'); $extra = '-9 -r'; pake_sh("$cmd $distFile $extra ".basename(Builder::distDir())); } @@ -164,6 +308,7 @@ function run_dist($task=null, $args=array(), $cliOpts=array()) rename($pharFile, $distFile); } } + chdir($cwd); } /** @@ -180,9 +325,10 @@ pake_task( 'default' ); // internal task: parse cli options pake_task('getopts'); pake_task('init', 'getopts'); -pake_task('doc', 'getopts', 'init'); +pake_task('doc', 'getopts', 'init', 'clean-doc'); pake_task('build', 'getopts', 'init', 'doc'); pake_task('dist', 'getopts', 'init', 'build', 'clean-dist'); +pake_task('clean-doc', 'getopts'); pake_task('clean-dist', 'getopts'); pake_task('clean', 'getopts'); -- 2.43.0