Commit 361f202f authored by Ben Boeckel's avatar Ben Boeckel Committed by Kitware Robot

Merge topic 'module-system-docs'

c5fa36f0 ModuleSystem: document third party APIs and practices
911d524c ModuleSystem: document wrapping
17a56b09 ModuleSystem: add high-level overview of the new build system
942e5cae doxygen: generate doxygen from module system files
ba4a062b doxygen: strip the build path from the generated source
913171a5 doxygen: update references for new code
2e65f50f doxygen: update module searching for the new module system
828cadab doc_version: fix syntax errors
...
Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Merge-request: !6121
parents 77b8555e c5fa36f0
Pipeline #157370 failed with stage
in 0 seconds
......@@ -2729,10 +2729,10 @@ endfunction ()
@ingroup module
@section module-autoinit Autoinit
When a module contains a registry which may be populated by other modules,
these registries need to be populated when the modules are loaded by the
dynamic linker (for shared builds) or program load time (for static builds). To
provide for this, the module system contains an autoinit "subsystem".
When a module contains a factory which may be populated by other modules, these
factories need to be populated when the modules are loaded by the dynamic linker
(for shared builds) or program load time (for static builds). To provide for
this, the module system contains an autoinit "subsystem".
@subsection module-autoinit-leverage Leveraging the autoinit subsystem
......@@ -2758,7 +2758,7 @@ The @ref vtk_module_autoinit function will generate an include file and provide
its path via the `<module>_AUTOINIT_INCLUDE` define. once it has been included,
if the `<module>_AUTOINIT` symbol is defined, a header is included which is
intended to provide the `VTK_MODULE_AUTOINIT` macro. This macro is given the
module name and should use `<module>_AUTOINIT` to fill in the registries in the
module name and should use `<module>_AUTOINIT` to fill in the factories in the
module with those from the `IMPLEMENTS` modules listed in that symbol.
The `<module>_AUTOINIT` symbol's value is:
......
This diff is collapsed.
......@@ -33,22 +33,22 @@ endif()
# Build up a list of all module source directories. Note that this should be
# all source directories and so does not use the normal variables.
unset(VTK_MODULE_DIRS_DOXYGEN)
file(GLOB src RELATIVE "${VTK_SOURCE_DIR}" "${VTK_SOURCE_DIR}/*/*/module.cmake")
foreach(module ${src})
get_filename_component(module_BASE ${module} PATH)
if("${module_BASE}" MATCHES "^Utilities" OR ${module_BASE} MATCHES "^Third")
set(VTK_MODULE_DIRS_DOXYGEN "")
foreach(module IN LISTS vtk_module_files)
file(RELATIVE_PATH module_dir "${VTK_SOURCE_DIR}" "${module}")
get_filename_component(module_BASE ${module_dir} PATH)
if(module_BASE MATCHES "^Utilities" OR module_BASE MATCHES "^ThirdParty")
# Skip the utilities and third parties directories.
else()
# Use both the source and binary directories, this ensures that
# generated files will be included, but they may then be architecture,
# build configuration and/or compiler specific. All source directories
# are included whether the module is enabled or not.
set(VTK_MODULE_DIRS_DOXYGEN
"${VTK_MODULE_DIRS_DOXYGEN}
\"${VTK_SOURCE_DIR}/${module_BASE}\"
\"${VTK_BINARY_DIR}/${module_BASE}\"")
endif()
continue()
endif ()
# Use both the source and binary directories, this ensures that
# generated files will be included, but they may then be architecture,
# build configuration and/or compiler specific. All source directories
# are included whether the module is enabled or not.
string(APPEND VTK_MODULE_DIRS_DOXYGEN
"\"${VTK_SOURCE_DIR}/${module_BASE}\"
\"${VTK_BINARY_DIR}/${module_BASE}\"
")
endforeach()
configure_file(
......
This diff is collapsed.
This diff is collapsed.
......@@ -260,6 +260,17 @@ foreach(var
FILES_MATCHING PATTERN "*.h"
)
endforeach()
file(COPY "${SOURCE_DIR}/CMake"
DESTINATION "${INTERMEDIATE_DOX_DIR}"
FILES_MATCHING
PATTERN "vtkDetectLibraryType.cmake"
PATTERN "vtkEncodeString.cmake"
PATTERN "vtkHashSource.cmake"
PATTERN "vtkModule*.cmake"
PATTERN "vtkModuleDebugging.cmake" EXCLUDE
PATTERN "vtkModuleRemote.cmake" EXCLUDE
PATTERN "vtkObjectFactory.cmake"
)
# ----------------------------------------------------------------------------
# Build the Events invocation list.
......
......@@ -152,24 +152,24 @@ print DEST_FILE
if exists $args{"logo"} && -f $args{"logo"};
print DEST_FILE
" \@par VTK:\n"
" VTK is an open-source software system for image processing, 3D \n"
" graphics, volume rendering and visualization. VTK includes many \n"
" advanced algorithms (e.g., surface reconstruction, implicit modelling, \n"
" decimation) and rendering techniques (e.g., hardware-accelerated \n"
" volume rendering, LOD control).\n"
" \@par \n"
" VTK is used by academicians for teaching and research; by government \n"
" research institutions such as Los Alamos National Lab in the US or \n"
" CINECA in Italy; and by many commercial firms who use VTK to build or \n"
" extend products. \n"
" \@par \n"
" The origin of VTK is with the textbook \"The Visualization Toolkit, an \n"
" Object-Oriented Approach to 3D Graphics\" originally published by \n"
" Prentice Hall and now published by Kitware, Inc. (Third Edition ISBN \n"
" 1-930934-07-6). VTK has grown (since its initial release in 1994) to a \n"
" world-wide user base in the commercial, academic, and research \n"
" communities. \n"
" \@par VTK:\n",
" VTK is an open-source software system for image processing, 3D \n",
" graphics, volume rendering and visualization. VTK includes many \n",
" advanced algorithms (e.g., surface reconstruction, implicit modelling, \n",
" decimation) and rendering techniques (e.g., hardware-accelerated \n",
" volume rendering, LOD control).\n",
" \@par \n",
" VTK is used by academicians for teaching and research; by government \n",
" research institutions such as Los Alamos National Lab in the US or \n",
" CINECA in Italy; and by many commercial firms who use VTK to build or \n",
" extend products. \n",
" \@par \n",
" The origin of VTK is with the textbook \"The Visualization Toolkit, an \n",
" Object-Oriented Approach to 3D Graphics\" originally published by \n",
" Prentice Hall and now published by Kitware, Inc. (Third Edition ISBN \n",
" 1-930934-07-6). VTK has grown (since its initial release in 1994) to a \n",
" world-wide user base in the commercial, academic, and research \n",
" communities. \n",
" \@par Useful links:\n",
" \@li VTK Home: http://www.vtk.org\n",
" \@li VTK Source: https://gitlab.kitware.com/vtk/vtk\n",
......@@ -177,8 +177,8 @@ print DEST_FILE
" \@li VTK FAQ: http://www.vtk.org/Wiki/VTK_FAQ\n",
" \@li VTK Wiki: http://www.vtk.org/Wiki/\n",
" \@li VTK Dashboard: http://www.cdash.org/CDash/index.php?project=VTK\n",
" \@li Commercial <a href=\"https://www.kitware.com/products/support.html\">support</a> "
" and <a href=\"http://www.kitware.com/products/protraining.php\">training<\a> "
" \@li Commercial <a href=\"https://www.kitware.com/products/support.html\">support</a> ",
" and <a href=\"http://www.kitware.com/products/protraining.php\">training</a> ",
" are available from Kitware\n",
" ",
"*/\n\n";
......
......@@ -6,6 +6,7 @@
PROJECT_NAME = VTK
FULL_PATH_NAMES = YES
STRIP_FROM_PATH = "@VTK_BINARY_DIR@/Utilities/Doxygen/dox"
WARN_IF_UNDOCUMENTED = NO
GENERATE_TREEVIEW = NO
......@@ -36,7 +37,7 @@ MAX_DOT_GRAPH_DEPTH = 3
ALLEXTERNALS = NO
IMAGE_PATH = "@VTK_SOURCE_DIR@/Utilities/Doxygen" "@VTK_BINARY_DIR@/Utilities/Doxygen/contrib" \
IMAGE_PATH = "@VTK_SOURCE_DIR@/Utilities/Doxygen" \
"@VTK_SOURCE_DIR@/Filters" \
"@VTK_SOURCE_DIR@/Geovis" \
"@VTK_SOURCE_DIR@/Rendering"
......@@ -56,20 +57,13 @@ INPUT = \
EXCLUDE_PATTERNS =
EXCLUDE = \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Common/Core/vtkSetGet.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Common/DataModel/vtkMarchingSquaresCases.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Common/DataModel/vtkMarchingCubesCases.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Common/DataModel/vtkMarchingSquaresLineCases.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Common/DataModel/vtkMarchingCubesTriangleCases.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Common/Core/vtkWindows.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Common/vtkTk.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Common/vtkPython.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Common/vtkPythonUtil.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Common/vtkJavaAwt.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Common/vtkJavaUtil.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Common/vtkPythonUtil.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Parallel/MPI/vtkMPI.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/IO/Import/vtk3DS.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/IO/Import/vtkVRML.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/IO/PLY/vtkPLY.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Rendering/OpenGL/vtkOpenGL.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Rendering/FreeType/fonts/vtkEmbeddedFonts.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Testing/Rendering/Testing/vtkRegressionTestImage.h" \
"@VTK_BINARY_DIR@/Utilities/Doxygen/dox/Testing/Core/Testing/vtkTestDriver.h" \
......@@ -96,7 +90,9 @@ HTML_TIMESTAMP = YES
SHORT_NAMES = @DOXYGEN_SHORT_NAMES@
# PAPER_TYPE = letter
FILE_PATTERNS = *.h *.md
FILE_PATTERNS = *.h *.md *.cmake
EXTENSION_MAPPING = cmake=c
FILTER_PATTERNS = *.cmake="@PERL_EXECUTABLE@ @VTK_SOURCE_DIR@/Utilities/Doxygen/filters/cmake2c.pl"
RECURSIVE = YES
ALPHABETICAL_INDEX = YES
......
#!/usr/bin/env perl
use warnings;
use strict;
my $fp;
open $fp, "<$ARGV[0]";
my $result = q{};
my $commentBlockStarted = 0;
my $functionStarted = 0;
for my $line (<$fp>) {
# remove trailing new lines
chomp $line;
# skip empty lines
if ($line =~ m{^\s*$}) {
$result .= "\n";
next;
}
# Inside comment block
if ($commentBlockStarted == 1) {
if ($line =~ m{#\]==\]}) {
$line =~ s{#\]==\]}{*/};
$commentBlockStarted = 0;
}
# replace bullets with '-', because '*' will be skipped by doxygen
$line =~ s{^\s*\*\s+}{ - };
$result .= "$line\n";
next;
}
# Inside function/macro. Replace content with empty lines so that
# definitions are at the correct line number.
if ($functionStarted == 1) {
if ($line =~ m{(^endfunction\s*\(.*\)|^endmacro\s*\(.*\))}) {
$result .= "}\n";
$functionStarted = 0;
next;
}
$result .= "\n";
next;
}
# Start comment block
if ($line =~ m{#\[==\[}) {
$line =~ s{#\[==\[}{/**};
$result .= "$line\n";
$commentBlockStarted = 1;
next;
}
# Replace normal comment with empty line
if ($line =~ m{^\s*#}) {
$result .= "\n";
next;
}
# Remove end-of-line comment
$line =~ s{#.*}{};
# Start function/macro
if ($line =~ m{(^function\s*\()|(^macro\s*\()}) {
$functionStarted = 1;
if ($line =~ m{^function\s*\(}) {
$result .= "function ";
$line =~ s{^function\s*\(}{};
}
elsif ($line =~ m{^macro\s*\(}) {
$result .= "macro ";
$line =~ s{^macro\s*\(}{};
}
# first argument is the name of the function/macro,
# then the arguments
$line =~ s{\)\s*$}{};
my @args = split(' ', $line);
$result .= $args[0];
shift(@args);
$result .= " (";
for my $arg (@args) {
$result .= $arg;
if ($arg ne $args[-1]) {
$result .= " ,";
}
}
$result .= ") {\n";
next;
}
# All other lines, replace with empty lines
$result .= "\n";
next;
}
print $result;
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