Commit 0044394f authored by Utkarsh Ayachit's avatar Utkarsh Ayachit

Updating the code to generate documentation from XMLs.

* Removed vtkSMExtractDocumentation. Instead using a XSLT based logic to
  generate the html from the XMLs.
* Added new macro in ParaViewMacros to generate the HTMLs from XML.
* Update ParaView/Documentation CMakeLists.txt file to use the new XSL logic.

This adds a dependency on the Qt executable "xmlpatterns". xmlpatterns has been
available since Qt 4.6 so this should not be an issue.

Change-Id: I56dee62e6d20f2b5f739cc1f7a6098c66e168311
parent d7c252f4
......@@ -84,8 +84,8 @@ ParaViewMainWindow::ParaViewMainWindow()
// Enable help for from the object inspector.
QObject::connect(this->Internals->objectInspector,
SIGNAL(helpRequested(QString)),
this, SLOT(showHelpForProxy(const QString&)));
SIGNAL(helpRequested(const QString&, const QString&)),
this, SLOT(showHelpForProxy(const QString&, const QString&)));
// Populate application menus with actions.
pqParaViewMenuBuilders::buildFileMenu(*this->Internals->menu_File);
......@@ -129,8 +129,10 @@ ParaViewMainWindow::~ParaViewMainWindow()
//-----------------------------------------------------------------------------
void ParaViewMainWindow::showHelpForProxy(const QString& proxyname)
void ParaViewMainWindow::showHelpForProxy(const QString& groupname, const
QString& proxyname)
{
pqHelpReaction::showHelp(
QString("qthelp://paraview.org/paraview/%1.html").arg(proxyname));
QString("qthelp://paraview.org/paraview/%1.%2.html").arg(
groupname).arg(proxyname));
}
......@@ -44,7 +44,7 @@ public:
~ParaViewMainWindow();
protected slots:
void showHelpForProxy(const QString& proxyname);
void showHelpForProxy(const QString& proxyname, const QString& groupname);
private:
ParaViewMainWindow(const ParaViewMainWindow&); // Not implemented.
......
if(WIN32)
get_filename_component(QT_BIN_DIR "@QT_QMAKE_EXECUTABLE@" PATH)
get_filename_component(PYTHON_BIN "@PYTHON_EXECUTABLE@" PATH)
get_filename_component(MPI_BIN "@MPIEXEC@" PATH)
set(ENV{PATH} "${MPI_BIN};${PYTHON_BIN};${QT_BIN_DIR};@PARAVIEW_FIXUP_BUNDLE_SEARCH_PATHS@;$ENV{PATH}")
elseif(APPLE)
set(dyld_lib_path "@QT_LIBRARY_DIR@:$ENV{DYLD_LIBRARY_PATH}")
set(SEARCH_PATHS @PARAVIEW_FIXUP_BUNDLE_SEARCH_PATHS@)
foreach(path ${SEARCH_PATHS})
set(dyld_lib_path "${dyld_lib_path}:${path}")
endforeach()
# Macs are stupid and will try to load an external png before loading the system libPng.dylib if something linked against it.
set(ENV{DYLD_LIBRARY_PATH} /System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/ImageIO.framework/Versions/A/Resources:${dyld_lib_path})
else(WIN32)
get_filename_component(PYTHON_LIB "@PYTHON_LIBRARY@" PATH)
get_filename_component(MPI_LIB "@MPI_LIBRARY@" PATH)
set(ld_lib_path "${MPI_LIB}:${PYTHON_LIB}:@QT_LIBRARY_DIR@:$ENV{LD_LIBRARY_PATH}")
set(SEARCH_PATHS @PARAVIEW_FIXUP_BUNDLE_SEARCH_PATHS@)
foreach(path ${SEARCH_PATHS})
set(ld_lib_path "${ld_lib_path}:${path}")
endforeach()
set(ENV{LD_LIBRARY_PATH} ${ld_lib_path})
endif(WIN32)
execute_process(
COMMAND "@ParaView_BINARY_DIR@/bin/${OutDir}/vtkSMExtractDocumentation" "@ParaView_BINARY_DIR@/Documentation" "${fullXMLFile}"
WORKING_DIR @ParaView_BINARY_DIR@
)
......@@ -217,3 +217,49 @@ FUNCTION (protobuf_generate out_cpp_file in_proto_file)
DEPENDS ${in_proto_file} protoc_compiler
)
ENDFUNCTION (protobuf_generate)
#------------------------------------------------------------------------------
# GENERATE_HTMLS_FROM_XMLS can be used to generate HTML files for
# from a given list of xml files that correspond to server manager xmls.
# ARGUMENTS:
# xmlpatterns: IN : Qt xmlpatterns executable.
# xmls: IN : full pathnames to xml files.
# output_dir : IN : full path to output directory where to generate the htmls.
# target : IN : name of the target to add the dependencies to.
#------------------------------------------------------------------------------
function (generate_htmls_from_xmls xmlpatterns xmls output_dir output_files)
set (dependencies)
foreach(xml ${xmls})
get_filename_component(xml_name_we ${xml} NAME_WE)
get_filename_component(xml_name ${xml} NAME)
add_custom_command(
OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/${xml_name_we}.final"
# process each XML using the XSL to generate the html.
COMMAND "${xmlpatterns}"
"${ParaView_CMAKE_DIR}/smdocumentation_generator.xsl"
"${xml}"
-output
"${CMAKE_CURRENT_BINARY_DIR}/${xml_name_we}.inter"
# process each html file to sperate it out into files for each proxy.
COMMAND "${CMAKE_COMMAND}"
-Dinput_file="${CMAKE_CURRENT_BINARY_DIR}/${xml_name_we}.inter"
-Doutput_dir="${output_dir}"
-Doutput_file="${CMAKE_CURRENT_BINARY_DIR}/${xml_name_we}.final"
-P "${ParaView_CMAKE_DIR}/split_htmls.cmake"
DEPENDS "${xml}"
"${ParaView_CMAKE_DIR}/smdocumentation_generator.xsl"
"${ParaView_CMAKE_DIR}/split_htmls.cmake"
WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
COMMENT "Generating Documentation HTMLS for \"${xml_name}\"")
set (dependencies ${dependencies}
"${CMAKE_CURRENT_BINARY_DIR}/${xml_name_we}.final")
endforeach()
set (${output_files} ${dependencies} PARENT_SCOPE)
endfunction()
<?xml version="1.0" encoding="utf8"?>
<!-- XSL used to generate HTMLs from server manager XML
to run use : xmlpatterns <xsl> <xml> -output <html>
-->
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html"/>
<xsl:template match="ServerManagerConfiguration/ProxyGroup">
<xsl:variable name="group_name" select="@name" />
<xsl:for-each select="SourceProxy|Proxy">
<html>
<head>
<meta name="proxy_name"><xsl:value-of select="$group_name" />:<xsl:value-of select="@name" /></meta>
</head>
<body>
<h2><xsl:choose>
<xsl:when test="@label"> <xsl:value-of select="@label" /> </xsl:when>
<xsl:otherwise> <xsl:value-of select="@name" /> </xsl:otherwise>
</xsl:choose> (<xsl:value-of select="@name"/>) </h2>
<xsl:apply-templates select="Documentation" />
<table width="97%" border="2px" >
<tr bgcolor="#9acd32">
<th>Property</th>
<th width="60%">Description</th>
<th width="5%">Default(s)</th>
<th width="20%">Restrictions</th>
</tr>
<xsl:for-each select="DoubleVectorProperty|InputProperty|IntVectorProperty|StringVectorProperty|ProxyProperty|IdTypeVectorProperty">
<tr>
<th>
<xsl:choose>
<xsl:when test="@label"><xsl:value-of select="@label"/></xsl:when>
<xsl:otherwise><xsl:value-of select="@name"/></xsl:otherwise>
</xsl:choose>
</th>
<td>
<xsl:apply-templates select="Documentation" />
</td>
<td>
<div class="defaults">
<xsl:call-template name="WriteDefaults" />
</div>
</td>
<td>
<div class="domain">
<xsl:call-template name="WriteDomain" />
</div>
</td>
</tr>
</xsl:for-each>
</table>
</body>
</html>
</xsl:for-each>
</xsl:template>
<!-- Defaults Handler -->
<xsl:template name="WriteDefaults">
<xsl:if test="@default_values">
<xsl:value-of select="@default_values" />
</xsl:if>
</xsl:template>
<!-- Domains Handler -->
<xsl:template name="WriteDomain">
<xsl:apply-templates select="ArrayListDomain" />
<xsl:apply-templates select="ArrayRangeDomain" />
<xsl:apply-templates select="ArraySelectionDomain" />
<xsl:apply-templates select="BooleanDomain" />
<xsl:apply-templates select="BoundsDomain" />
<xsl:apply-templates select="DataTypeDomain" />
<xsl:apply-templates select="DoubleRangeDomain" />
<xsl:apply-templates select="IntRangeDomain" />
<xsl:apply-templates select="EnumerationDomain" />
<xsl:apply-templates select="ExtentDomain" />
<xsl:apply-templates select="FieldDataDomain" />
<xsl:apply-templates select="FileListDomain" />
<xsl:apply-templates select="FixedTypeDomain" />
<xsl:apply-templates select="InputArrayDomain" />
<xsl:apply-templates select="ProxyGroupDomain" />
<xsl:apply-templates select="ProxyListDomain" />
<xsl:apply-templates select="StringListDomain" />
</xsl:template>
<xsl:template match="StringListDomain">
The value(s) can be one of the following:
<ul>
<xsl:for-each select="String">
<li><xsl:value-of select="@value"/></li>
</xsl:for-each>
</ul>
</xsl:template>
<xsl:template match="ProxyListDomain">
The value can be one of the following:
<ul>
<xsl:for-each select="Proxy">
<li><xsl:value-of select="@name"/>
(<i><xsl:value-of select="@group"/></i>)
</li>
</xsl:for-each>
</ul>
</xsl:template>
<xsl:template match="ProxyGroupDomain">
<!-- ugh, ignore this domain. It's pretty pointless anyways.-->
</xsl:template>
<xsl:template match="ExtentDomain">
The value(s) must lie within the structured-extents of the input dataset.
</xsl:template>
<xsl:template match="FieldDataDomain">
The value must be field array name.
</xsl:template>
<xsl:template match="FileListDomain">
The value(s) must be a filename (or filenames).
</xsl:template>
<xsl:template match="FixedTypeDomain">
Once set, the input dataset cannot be changed.
</xsl:template>
<xsl:template match="InputArrayDomain">
The dataset much contain a field array (
<xsl:value-of select="@attribute_type"/>)
<xsl:if test="@number_of_components">
with <xsl:value-of select="@number_of_components"/> component(s).
</xsl:if>
</xsl:template>
<xsl:template match="EnumerationDomain">
The value(s) is an enumeration of the following:
<ul>
<xsl:for-each select="Entry">
<li><xsl:value-of select="@text"/> (
<xsl:value-of select="@value"/>)</li>
</xsl:for-each>
</ul>
</xsl:template>
<xsl:template match="ArrayListDomain[@attribute_type='Scalars']">
<!-- Handle ArrayListDomain -->
An array of scalars is required.
</xsl:template>
<xsl:template match="ArrayListDomain[@attribute_type='Vectors']">
<!-- Handle ArrayListDomain -->
An array of vectors is required.
</xsl:template>
<xsl:template match="ArrayRangeDomain">
The value must lie within the range of the selected data array.
</xsl:template>
<xsl:template match="ArraySelectionDomain">
The list of array names is provided by the reader.
</xsl:template>
<xsl:template match="BoundsDomain[@mode='normal']">
The value must lie within the bounding box of the dataset.
<xsl:if test="@default_mode">
It will default to the <xsl:value-of select="@default_mode" /> in each dimension.
</xsl:if>
</xsl:template>
<xsl:template match="BoundsDomain[@mode='magnitude']">
Determine the length of the dataset's diagonal.
The value must lie within -diagonal length to +diagonal length.
</xsl:template>
<xsl:template match="BoundsDomain[@mode='scaled_extent']">
The value must be less than the largest dimension of the
dataset multiplied by a scale factor of
<xsl:value-of select="@scale_factor" />.
</xsl:template>
<xsl:template match="DoubleRangeDomain">
<xsl:call-template name="RangeDomain"/>
</xsl:template>
<xsl:template match="IntRangeDomain">
<xsl:call-template name="RangeDomain"/>
</xsl:template>
<xsl:template name="RangeDomain">
Value(s) must be in the range (
<xsl:value-of select="@min"/>,
<xsl:value-of select="@max"/>).
</xsl:template>
<xsl:template match="DataTypeDomain">
Accepts input of following types:
<ul>
<xsl:for-each select="DataType">
<li><xsl:value-of select="@value" /> </li>
</xsl:for-each>
</ul>
</xsl:template>
<xsl:template match="BooleanDomain">
Accepts boolean values (0 or 1).
</xsl:template>
<!-- Documentation Handler -->
<xsl:template match="Documentation">
<xsl:choose>
<xsl:when test="@long_help">
<i><p> <xsl:value-of select="@long_help" /></p></i>
</xsl:when>
<xsl:otherwise>
<xsl:if test="@short_help">
<i><p> <xsl:value-of select="@short_help" /></p></i>
</xsl:if>
</xsl:otherwise>
</xsl:choose>
<div class="description"><xsl:value-of select="." /></div>
</xsl:template>
</xsl:stylesheet>
# This file is used by generate_htmls_from_xmls function in ParaViewMacros.cmake
# to split a file consisting of multiple htmls into multiple files.
cmake_minimum_required(VERSION 2.8)
file(READ "${input_file}" multiple_htmls)
# if the contents of input_file contains ';', then CMake gets confused.
# So replace all semicolons with a placeholder.
string(REPLACE ";" "\\semicolon" multiple_htmls "${multiple_htmls}")
# Convert the single string into a list split at </html> markers.
string(REPLACE "</html>" "</html>;" multiple_htmls_as_list "${multiple_htmls}")
# Generate output HTML for each <html>..</html> chunk in the input.
foreach (single_html ${multiple_htmls_as_list})
set (proxy_name)
set (group_name)
string(REGEX MATCH "<meta[^>]*name=\"proxy_name\".*>([a-zA-Z0-9_-]+):([a-zA-Z0-9_-]+)</meta>"
tmp "${single_html}")
if (CMAKE_MATCH_2)
set(proxy_name ${CMAKE_MATCH_2})
endif()
if (CMAKE_MATCH_1)
set(group_name ${CMAKE_MATCH_1})
endif()
if (group_name)
# process formatting strings.
string (REPLACE "\\semicolon" ";" single_html "${single_html}")
string (REGEX REPLACE "\\\\bold{([^}]+)}" "<b>\\1</b>" single_html "${single_html}")
string (REGEX REPLACE "\\\\emph{([^}]+)}" "<i>\\1</i>" single_html "${single_html}")
file (WRITE "${output_dir}/${group_name}.${proxy_name}.html" "${single_html}")
endif()
endforeach()
# write the output file
file(WRITE "${output_file}" "done")
......@@ -14,36 +14,39 @@ configure_file(
"${CMAKE_CURRENT_BINARY_DIR}/about.html"
@ONLY)
OPTION(PARAVIEW_GENERATE_PROXY_DOCUMENTATION
"Turn on to ensure that the documentation for filters/sources/readers and writers is built."
OFF)
FIND_PROGRAM(QT_HELP_GENERATOR
qhelpgenerator
PATHS "${QT_BINARY_DIR}"
DOC "qhelpgenerator used to compile Qt help project files")
MARK_AS_ADVANCED(PARAVIEW_GENERATE_PROXY_DOCUMENTATION)
set (extra_dependencies)
IF (PARAVIEW_GENERATE_PROXY_DOCUMENTATION)
# This dependency ensures that the ParaViewFiles.html and other files are
# generated before the qch file is attempted to be generated.
set(extra_dependencies HTMLDocumentation)
ENDIF (PARAVIEW_GENERATE_PROXY_DOCUMENTATION)
FIND_PROGRAM(QT_XMLPATTERNS_EXECUTABLE
xmlpatterns
PATHS "${QT_BINARY_DIR}"
DOC "xmlpatterns used to generate html from Proxy documentation.")
MARK_AS_ADVANCED(QT_HELP_GENERATOR QT_XMLPATTERNS_EXECUTABLE)
# generate htmls from the server manager xmls.
generate_htmls_from_xmls(
"${QT_XMLPATTERNS_EXECUTABLE}"
"${PARAVIEW_SERVERMANAGER_XMLS}"
"${CMAKE_CURRENT_BINARY_DIR}"
proxy_html_outputs)
message("${proxy_html_outputs}")
ADD_CUSTOM_COMMAND(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/paraview.qch
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/paraview.qhp
${extra_dependencies}
${proxy_html_outputs}
COMMAND ${QT_HELP_GENERATOR}
ARGS ${CMAKE_CURRENT_BINARY_DIR}/paraview.qhp
-o ${CMAKE_CURRENT_BINARY_DIR}/paraview.qch
COMMENT "Compiling Qt help project paraview.qhp"
)
ADD_CUSTOM_TARGET(ParaViewOnlineHelp
ADD_CUSTOM_TARGET (ParaViewOnlineHelp
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/paraview.qch)
SET(USERS_GUIDE_FILE "ParaView User's Guide ${PARAVIEW_VERSION}.pdf")
FIND_FILE(PARAVIEW_USERS_GUIDE ${USERS_GUIDE_FILE})
MARK_AS_ADVANCED(PARAVIEW_USERS_GUIDE)
......
......@@ -135,6 +135,9 @@ IF(PARAVIEW_ENABLE_PYTHON)
ENDIF(PARAVIEW_ENABLE_PYTHON_FILTERS)
ENDIF(PARAVIEW_ENABLE_PYTHON)
SET (PARAVIEW_SERVERMANAGER_XMLS ${resourceFiles}
CACHE INTERNAL "Server Manager XMLs")
#needs to depend on vtkParaViewIncludeModulesToSMApplication so
#we can regenerate when python filters or VisItBridge are toggled on/off
SET(CMD_DEP kwProcessXML)
......
......@@ -285,49 +285,6 @@ ADD_CUSTOM_COMMAND(
COMMENT "generating ${MIN_INIT_SRC}")
ENDIF(PARAVIEW_MINIMAL_BUILD)
SET(GUI_CONFIG_FILES
ParaViewSources
ParaViewFilters
ParaViewReaders
ParaViewWriters
)
IF(NOT CMAKE_CROSSCOMPILING)
add_executable_with_forwarding(PV_EXE_SUFFIX
vtkSMExtractDocumentation vtkSMExtractDocumentation.cxx)
TARGET_LINK_LIBRARIES(vtkSMExtractDocumentation${PV_EXE_SUFFIX} vtkPVServerManager)
EXPORT(TARGETS vtkSMExtractDocumentation${PV_EXE_SUFFIX} FILE ${EXPORT_EXECUTABLES_FILE} NAMESPACE "${EXPORT_EXECUTABLES_NAMESPACE}" APPEND)
ENDIF(NOT CMAKE_CROSSCOMPILING)
# FIXME: DUDE! Dependency on Qt code in ServerManager!!!!
CONFIGURE_FILE(${ParaView_CMAKE_DIR}/ExecuteSMExtractDocumentation.cmake.in
${ParaView_BINARY_DIR}/CMake/ExecuteSMExtractDocumentation.cmake
@ONLY)
FOREACH(gcf ${GUI_CONFIG_FILES})
SET(fullXMLFile ${ParaView_SOURCE_DIR}/Applications/ParaView/${gcf}.xml)
SET(fullHTMLFile ${ParaView_BINARY_DIR}/Documentation/${gcf}.html)
# run the following cmake script so that we can set the runtime path for Qt when executing
# SMExtractDocumentation during the build.
ADD_CUSTOM_COMMAND(
OUTPUT ${fullHTMLFile}
DEPENDS ${fullXMLFile} ${resourceFiles} vtkSMExtractDocumentation
COMMAND ${CMAKE_COMMAND}
ARGS -DfullXMLFile=${fullXMLFile} -DOutDir=${CMAKE_CFG_INTDIR} -P ${ParaView_BINARY_DIR}/CMake/ExecuteSMExtractDocumentation.cmake
COMMENT "Creating Documentation for ${gcf}"
)
SET(HTML_RESULTS ${HTML_RESULTS} ${fullHTMLFile})
ENDFOREACH(gcf)
ADD_CUSTOM_TARGET(HTMLDocumentation
DEPENDS ${HTML_RESULTS}
)
SET (HTMLDocumentation_FILES ${HTML_RESULTS} CACHE INTERNAL
"HTMLDocumentation files generated from ServerManager")
# including MINI_INIT -nix
# SET_SOURCE_FILES_PROPERTIES(vtkSMApplication.cxx PROPERTIES OBJECT_DEPENDS
# ${CMAKE_CURRENT_BINARY_DIR}/${MINI_INIT})
......
......@@ -739,6 +739,9 @@ void pqObjectInspectorWidget::showHelp()
if(this->CurrentPanel && this->CurrentPanel->referenceProxy())
{
this->helpRequested(this->CurrentPanel->referenceProxy()->getProxy()->GetXMLName());
this->helpRequested(
this->CurrentPanel->referenceProxy()->getProxy()->GetXMLGroup(),
this->CurrentPanel->referenceProxy()->getProxy()->GetXMLName());
}
}
......
......@@ -128,6 +128,7 @@ signals:
void viewChanged(pqView*);
void helpRequested(const QString& proxyType);
void helpRequested(const QString& groupname, const QString& proxyType);
void canAccept();
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment