From 4d6a5adb526dd86028936f8fea968ec4c127fe1e Mon Sep 17 00:00:00 2001 From: Alexandre Emsenhuber Date: Wed, 25 Jun 2008 13:42:01 +0000 Subject: [PATCH] Some tweaks to the doxygen doc: * Removed maintenance/mwdoxygen.cfg file and "make doxydoc", doxygen is already supported by default in mwdocgen.php * Added svn revisions numbers to the doc if Subversion is installed. --- bin/svnstat | 2 +- maintenance/Doxyfile | 12 +- maintenance/Makefile | 11 +- maintenance/mwdocgen.php | 155 +++++++++++++++---------- maintenance/mwdoxygen.cfg | 230 -------------------------------------- 5 files changed, 104 insertions(+), 306 deletions(-) delete mode 100644 maintenance/mwdoxygen.cfg diff --git a/bin/svnstat b/bin/svnstat index b134cdc2ff..5a2c940b5e 100755 --- a/bin/svnstat +++ b/bin/svnstat @@ -1,2 +1,2 @@ #!/bin/sh -svn stat -v $1 | sed -n 's/^[ A-Z?\*|!]\{1,15\}/r/;s/ \{1,15\}/\/r/;s/ .*//p' +svn stat -v $1 | sed -n 's/^[ A-Z?\*|!]\{1,15\}[0-9]\{1,10\} \{1,15\}/r/;s/ .*//p' diff --git a/maintenance/Doxyfile b/maintenance/Doxyfile index 6c9811d082..df67ba6066 100644 --- a/maintenance/Doxyfile +++ b/maintenance/Doxyfile @@ -1,16 +1,18 @@ -# Doxyfile 1.4.6 +# Doxyfile 1.5.1 # # Some placeholders have been added for MediaWiki usage: # {{OUTPUT_DIRECTORY}} +# {{CURRENT_VERSION}} # {{STRIP_FROM_PATH}} +# {{SVNSTAT}} # {{INPUT}} #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- PROJECT_NAME = MediaWiki -PROJECT_NUMBER = trunk +PROJECT_NUMBER = {{CURRENT_VERSION}} OUTPUT_DIRECTORY = {{OUTPUT_DIRECTORY}} CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English @@ -39,7 +41,7 @@ MULTILINE_CPP_IS_BRIEF = NO DETAILS_AT_TOP = NO INHERIT_DOCS = YES SEPARATE_MEMBER_PAGES = NO -TAB_SIZE = 8 +TAB_SIZE = 4 ALIASES = OPTIMIZE_OUTPUT_FOR_C = NO OPTIMIZE_OUTPUT_JAVA = NO @@ -74,7 +76,7 @@ ENABLED_SECTIONS = MAX_INITIALIZER_LINES = 30 SHOW_USED_FILES = YES SHOW_DIRECTORIES = NO -FILE_VERSION_FILTER = +FILE_VERSION_FILTER = {{SVNSTAT}} #--------------------------------------------------------------------------- # configuration options related to warning and progress messages #--------------------------------------------------------------------------- @@ -132,7 +134,7 @@ FILE_PATTERNS = *.c \ *.PY RECURSIVE = YES EXCLUDE = -EXCLUDE_SYMLINKS = NO +EXCLUDE_SYMLINKS = YES EXCLUDE_PATTERNS = LocalSettings.php AdminSettings.php EXAMPLE_PATH = EXAMPLE_PATTERNS = * diff --git a/maintenance/Makefile b/maintenance/Makefile index 99c5724e3f..82476139f4 100644 --- a/maintenance/Makefile +++ b/maintenance/Makefile @@ -1,17 +1,10 @@ -mediawiki_version := $(shell php -r "include('commandLine.inc'); print SpecialVersion::getVersion();") - help: @echo "Run 'make test' to run the parser tests." - @echo "Run 'make doc' to run the phpdoc generation." - @echo "Run 'make doxydoc' (unsupported doxygen generation)." + @echo "Run 'make doc' to run the doxygen generation." test: php parserTests.php --quiet doc: php mwdocgen.php --all - echo 'Doc generation done. Look at ./docs/html/' - -doxydoc: - cd .. && /bin/sed -e "s/MW_VERSION_PLACEHOLDER/$(mediawiki_version)/" maintenance/mwdoxygen.cfg | doxygen - - echo 'Doc generation done. Look at ./docs/html/' + @echo 'Doc generation done. Look at ./docs/html/' diff --git a/maintenance/mwdocgen.php b/maintenance/mwdocgen.php index 1e4eed8ac4..378229e0cd 100644 --- a/maintenance/mwdocgen.php +++ b/maintenance/mwdocgen.php @@ -46,6 +46,9 @@ $doxygenBin = 'doxygen'; /** doxygen configuration template for mediawiki */ $doxygenTemplate = $mwPath . 'maintenance/Doxyfile'; +/** svnstat command, used to get the version of each file */ +$svnstat = $mwPath . 'bin/svnstat'; + /** where Phpdoc should output documentation */ #$doxyOutput = '/var/www/mwdoc/'; $doxyOutput = $mwPath . 'docs' . DIRECTORY_SEPARATOR ; @@ -59,47 +62,87 @@ $mwPathS = $mwPath.'skins/'; /** Variable to get user input */ $input = ''; -/** shell command that will be run */ -$command = $doxygenBin; - # # Functions # -function readaline( $prompt = '') { +/** + * Read a line from the shell + * @param $prompt String + */ +function readaline( $prompt = '' ){ print $prompt; $fp = fopen( "php://stdin", "r" ); $resp = trim( fgets( $fp, 1024 ) ); fclose( $fp ); return $resp; +} + +/** + * Copied from SpecialVersion::getSvnRevision() + * @param $dir String + * @return Mixed: string or false + */ +function getSvnRevision( $dir ) { + // http://svnbook.red-bean.com/nightly/en/svn.developer.insidewc.html + $entries = $dir . '/.svn/entries'; + + if( !file_exists( $entries ) ) { + return false; } + $content = file( $entries ); + + // check if file is xml (subversion release <= 1.3) or not (subversion release = 1.4) + if( preg_match( '/^<\?xml/', $content[0] ) ) { + // subversion is release <= 1.3 + if( !function_exists( 'simplexml_load_file' ) ) { + // We could fall back to expat... YUCK + return false; + } + + $xml = simplexml_load_file( $entries ); + + if( $xml ) { + foreach( $xml->entry as $entry ) { + if( $xml->entry[0]['name'] == '' ) { + // The directory entry should always have a revision marker. + if( $entry['revision'] ) { + return intval( $entry['revision'] ); + } + } + } + } + return false; + } else { + // subversion is release 1.4 + return intval( $content[3] ); + } +} + /** * Generate a configuration file given user parameters and return the temporary filename. * @param $doxygenTemplate String: full path for the template. * @param $outputDirectory String: directory where the stuff will be output. * @param $stripFromPath String: path that should be stripped out (usually mediawiki base path). + * @param $currentVersion String: Version number of the software + * @param $svnstat String: path to the svnstat file * @param $input String: Path to analyze. */ -function generateConfigFile($doxygenTemplate, $outputDirectory, $stripFromPath, $input) { - global $tmpPath ; +function generateConfigFile( $doxygenTemplate, $outputDirectory, $stripFromPath, $currentVersion, $svnstat, $input ){ + global $tmpPath; - $template = file_get_contents($doxygenTemplate); + $template = file_get_contents( $doxygenTemplate ); // Replace template placeholders by correct values. - $tmpCfg = str_replace( - array( - '{{OUTPUT_DIRECTORY}}', - '{{STRIP_FROM_PATH}}', - '{{INPUT}}', - ), - array( - $outputDirectory, - $stripFromPath, - $input, - ), - $template - ); + $replacements = array( + '{{OUTPUT_DIRECTORY}}' => $outputDirectory, + '{{STRIP_FROM_PATH}}' => $stripFromPath, + '{{CURRENT_VERSION}}' => $currentVersion, + '{{SVNSTAT}}' => $svnstat, + '{{INPUT}}' => $input, + ); + $tmpCfg = str_replace( array_keys( $replacements ), array_values( $replacements ), $template ); $tmpFileName = $tmpPath . 'mwdocgen'. rand() .'.tmp'; file_put_contents( $tmpFileName , $tmpCfg ) or die("Could not write doxygen configuration to file $tmpFileName\n"); @@ -128,14 +171,18 @@ if( is_array( $argv ) && isset( $argv[1] ) ) { } } +// TODO : generate a list of paths )) + if( $input === '' ) { -?>Several documentation possibilities: + echo << +echo << +$command --------------------------------------------------- - +passthru( $command ); + +echo << - - +TEXT; diff --git a/maintenance/mwdoxygen.cfg b/maintenance/mwdoxygen.cfg deleted file mode 100644 index b5ba8925e3..0000000000 --- a/maintenance/mwdoxygen.cfg +++ /dev/null @@ -1,230 +0,0 @@ -# Doxyfile 1.5.1 - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- -PROJECT_NAME = MediaWiki -PROJECT_NUMBER = MW_VERSION_PLACEHOLDER -OUTPUT_DIRECTORY = docs -CREATE_SUBDIRS = NO -OUTPUT_LANGUAGE = English -USE_WINDOWS_ENCODING = NO -BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = YES -ABBREVIATE_BRIEF = -ALWAYS_DETAILED_SEC = YES -INLINE_INHERITED_MEMB = NO -FULL_PATH_NAMES = YES -STRIP_FROM_PATH = -STRIP_FROM_INC_PATH = -SHORT_NAMES = NO -JAVADOC_AUTOBRIEF = YES -MULTILINE_CPP_IS_BRIEF = NO -DETAILS_AT_TOP = YES -INHERIT_DOCS = YES -SEPARATE_MEMBER_PAGES = NO -TAB_SIZE = 4 -ALIASES = -OPTIMIZE_OUTPUT_FOR_C = NO -OPTIMIZE_OUTPUT_JAVA = NO -BUILTIN_STL_SUPPORT = NO -DISTRIBUTE_GROUP_DOC = NO -SUBGROUPING = YES -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- -EXTRACT_ALL = YES -EXTRACT_PRIVATE = YES -EXTRACT_STATIC = YES -EXTRACT_LOCAL_CLASSES = YES -EXTRACT_LOCAL_METHODS = NO -HIDE_UNDOC_MEMBERS = NO -HIDE_UNDOC_CLASSES = NO -HIDE_FRIEND_COMPOUNDS = NO -HIDE_IN_BODY_DOCS = NO -INTERNAL_DOCS = NO -CASE_SENSE_NAMES = YES -HIDE_SCOPE_NAMES = NO -SHOW_INCLUDE_FILES = YES -INLINE_INFO = YES -SORT_MEMBER_DOCS = YES -SORT_BRIEF_DOCS = NO -SORT_BY_SCOPE_NAME = NO -GENERATE_TODOLIST = YES -GENERATE_TESTLIST = YES -GENERATE_BUGLIST = YES -GENERATE_DEPRECATEDLIST= YES -ENABLED_SECTIONS = -MAX_INITIALIZER_LINES = 30 -SHOW_USED_FILES = YES -SHOW_DIRECTORIES = YES -FILE_VERSION_FILTER = bin/svnstat -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- -QUIET = NO -WARNINGS = YES -WARN_IF_UNDOCUMENTED = YES -WARN_IF_DOC_ERROR = YES -WARN_NO_PARAMDOC = NO -WARN_FORMAT = "$file:$line: $text" -WARN_LOGFILE = -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- -INPUT = config \ - includes \ - maintenance \ - skins \ - tests -FILE_PATTERNS = *.php \ - *.inc -RECURSIVE = NO -EXCLUDE = -EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = -EXAMPLE_PATH = -EXAMPLE_PATTERNS = -EXAMPLE_RECURSIVE = NO -IMAGE_PATH = -INPUT_FILTER = -FILTER_PATTERNS = -FILTER_SOURCE_FILES = NO -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- -SOURCE_BROWSER = NO -INLINE_SOURCES = NO -STRIP_CODE_COMMENTS = YES -REFERENCED_BY_RELATION = YES -REFERENCES_RELATION = YES -REFERENCES_LINK_SOURCE = YES -USE_HTAGS = NO -VERBATIM_HEADERS = YES -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- -ALPHABETICAL_INDEX = NO -COLS_IN_ALPHA_INDEX = 5 -IGNORE_PREFIX = -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- -GENERATE_HTML = YES -HTML_OUTPUT = html -HTML_FILE_EXTENSION = .html -HTML_HEADER = -HTML_FOOTER = -HTML_STYLESHEET = -HTML_ALIGN_MEMBERS = YES -GENERATE_HTMLHELP = NO -CHM_FILE = -HHC_LOCATION = -GENERATE_CHI = NO -BINARY_TOC = NO -TOC_EXPAND = NO -DISABLE_INDEX = NO -ENUM_VALUES_PER_LINE = 4 -GENERATE_TREEVIEW = YES -TREEVIEW_WIDTH = 250 -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- -GENERATE_LATEX = NO -LATEX_OUTPUT = latex -LATEX_CMD_NAME = latex -MAKEINDEX_CMD_NAME = makeindex -COMPACT_LATEX = NO -PAPER_TYPE = a4wide -EXTRA_PACKAGES = -LATEX_HEADER = -PDF_HYPERLINKS = NO -USE_PDFLATEX = NO -LATEX_BATCHMODE = NO -LATEX_HIDE_INDICES = NO -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- -GENERATE_RTF = NO -RTF_OUTPUT = rtf -COMPACT_RTF = NO -RTF_HYPERLINKS = NO -RTF_STYLESHEET_FILE = -RTF_EXTENSIONS_FILE = -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- -GENERATE_MAN = NO -MAN_OUTPUT = man -MAN_EXTENSION = .3 -MAN_LINKS = NO -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- -GENERATE_XML = NO -XML_OUTPUT = xml -XML_SCHEMA = -XML_DTD = -XML_PROGRAMLISTING = YES -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- -GENERATE_AUTOGEN_DEF = NO -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- -GENERATE_PERLMOD = NO -PERLMOD_LATEX = NO -PERLMOD_PRETTY = YES -PERLMOD_MAKEVAR_PREFIX = -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- -ENABLE_PREPROCESSING = NO -MACRO_EXPANSION = NO -EXPAND_ONLY_PREDEF = NO -SEARCH_INCLUDES = YES -INCLUDE_PATH = -INCLUDE_FILE_PATTERNS = -PREDEFINED = -EXPAND_AS_DEFINED = -SKIP_FUNCTION_MACROS = YES -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- -TAGFILES = -GENERATE_TAGFILE = -ALLEXTERNALS = NO -EXTERNAL_GROUPS = YES -PERL_PATH = /usr/bin/perl -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- -CLASS_DIAGRAMS = YES -HIDE_UNDOC_RELATIONS = YES -HAVE_DOT = YES -CLASS_GRAPH = YES -COLLABORATION_GRAPH = NO -GROUP_GRAPHS = YES -UML_LOOK = NO -TEMPLATE_RELATIONS = NO -INCLUDE_GRAPH = YES -INCLUDED_BY_GRAPH = YES -CALL_GRAPH = NO -CALLER_GRAPH = NO -GRAPHICAL_HIERARCHY = YES -DIRECTORY_GRAPH = YES -DOT_IMAGE_FORMAT = png -DOT_PATH = -DOTFILE_DIRS = -MAX_DOT_GRAPH_WIDTH = 1024 -MAX_DOT_GRAPH_HEIGHT = 1024 -MAX_DOT_GRAPH_DEPTH = 0 -DOT_TRANSPARENT = NO -DOT_MULTI_TARGETS = NO -GENERATE_LEGEND = YES -DOT_CLEANUP = YES -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- -SEARCHENGINE = YES -- 2.20.1