From c2e1f488e445b32f293d27752ac1fdf9475ba994 Mon Sep 17 00:00:00 2001 From: Nikolay Tyukaev Date: Thu, 3 Dec 2020 14:02:38 +0300 Subject: [PATCH] doc updates (#3437) * doc updates * delete linkchecker_filter.yaml * parse doxygen log --- docs/CMakeLists.txt | 15 ++++-- docs/doxygen/doxygen-ignore.txt | 27 +++++++++++ docs/doxygen/ie_c_api.config | 2 + docs/doxygen/ie_docs.config | 8 ++-- docs/doxygen/ie_plugin_api.config | 2 + docs/doxygen/ie_py_api.config | 2 + docs/doxygen/linkchecker_filter.yaml | 4 -- docs/doxygen/log.py | 68 ++++++++++++++++++++++++++++ docs/doxygen/ngraph_cpp_api.config | 2 + docs/doxygen/ngraph_py_api.config | 2 + 10 files changed, 120 insertions(+), 12 deletions(-) create mode 100644 docs/doxygen/doxygen-ignore.txt delete mode 100644 docs/doxygen/linkchecker_filter.yaml create mode 100644 docs/doxygen/log.py diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 5d14fd7e16b..8c8d9b95036 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -70,6 +70,7 @@ function(build_docs) # Preprocessing scripts set(DOXY_MD_FILTER "${DOXYGEN_DIR}/doxy_md_filter.py") + set(DOXY_LOG_SCRIPT "${DOXYGEN_DIR}/log.py") set(PYX_FILTER "${DOXYGEN_DIR}/pyx_filter.py") file(GLOB_RECURSE doc_source_files @@ -193,6 +194,14 @@ function(build_docs) WORKING_DIRECTORY ${DOCS_BUILD_DIR} VERBATIM) + add_custom_command(TARGET ie_docs + POST_BUILD + COMMAND ${Python3_EXECUTABLE} ${DOXY_LOG_SCRIPT} --log ${DOCS_BUILD_DIR}/ie_docs.log + --exclude-links ".*?(omz_|pot_|gst_|workbench_).*?" + COMMENT "Parse doxygen log to find errors." + VERBATIM + ) + # Plugin API add_custom_target(plugin_api @@ -215,11 +224,9 @@ function(build_docs) # added linkcheker - if(EXISTS "${LINKCHECKER_PY}") + if(EXISTS "${LINKCHECKER}") add_custom_target(docs_check - COMMAND ${Python3_EXECUTABLE} "${LINKCHECKER_PY}" - "${DOCS_BUILD_DIR}/html/" -f "${DOXYGEN_DIR}/linkchecker_filter.yaml" - --no_recursive -l "${DOCS_BUILD_DIR}" + COMMAND ${Python3_EXECUTABLE} "${LINKCHECKER}" -v "${DOCS_BUILD_DIR}/html/" COMMENT "Check links in generated documentation" WORKING_DIRECTORY "${DOCS_BUILD_DIR}" VERBATIM) diff --git a/docs/doxygen/doxygen-ignore.txt b/docs/doxygen/doxygen-ignore.txt new file mode 100644 index 00000000000..aafa75f9bdf --- /dev/null +++ b/docs/doxygen/doxygen-ignore.txt @@ -0,0 +1,27 @@ +ngraph_cpp_api.tag +inference-engine/include/details/ie_so_pointer.hpp +docs/IE_DG/Extensibility_DG/Custom_ONNX_Ops.md +docs/install_guides/installing-openvino-windows.md +docs/get_started/get_started_linux.md +inference-engine/include/vpu/vpu_plugin_config.hpp +inference-engine/include/ie_parallel.hpp +inference-engine/include/ie_unicode.hpp +inference-engine/include/ie_compound_blob.h +docs/get_started/get_started_windows.md +inference-engine/include/gpu/gpu_context_api_va.hpp +inference-engine/include/ie_remote_context.hpp +docs/how_tos/how-to-links.md +inference-engine/include/vpu/vpu_config.hpp +docs/index.md +inference-engine/ie_bridges/python/sample/ngraph_function_creation_sample/README.md +inference-engine/include/ie_plugin_config.hpp +inference-engine/include/ie_data.h +inference-engine/include/ie_blob.h +docs/get_started/get_started_macos.md +inference-engine/include/ie_precision.hpp +docs/install_guides/deployment-manager-tool.md +inference-engine/ie_bridges/c/docs/api_overview.md +inference-engine/include/gpu/gpu_context_api_dx.hpp +inference-engine/include/gpu/gpu_context_api_ocl.hpp +inference-engine/include/vpu/myriad_config.hpp +docs/benchmarks/performance_int8_vs_fp32.md diff --git a/docs/doxygen/ie_c_api.config b/docs/doxygen/ie_c_api.config index 541a21efe54..1f7ef20ed88 100644 --- a/docs/doxygen/ie_c_api.config +++ b/docs/doxygen/ie_c_api.config @@ -24,3 +24,5 @@ INPUT = "@C_API@" HTML_OUTPUT = ie_c_api GENERATE_TAGFILE = "@DOCS_BUILD_DIR@/ie_c_api.tag" + +WARN_LOGFILE = @DOCS_BUILD_DIR@/ie_c_api.log \ No newline at end of file diff --git a/docs/doxygen/ie_docs.config b/docs/doxygen/ie_docs.config index c6264fac258..b3872e48970 100644 --- a/docs/doxygen/ie_docs.config +++ b/docs/doxygen/ie_docs.config @@ -811,7 +811,7 @@ WARN_FORMAT = "$file:$line: $text" # messages should be written. If left blank the output is written to standard # error (stderr). -WARN_LOGFILE = +WARN_LOGFILE = @DOCS_BUILD_DIR@/ie_docs.log #--------------------------------------------------------------------------- # Configuration options related to the input files @@ -1613,7 +1613,7 @@ FORMULA_MACROFILE = # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -USE_MATHJAX = NO +USE_MATHJAX = YES # When MathJax is enabled you can set the default output format to be used for # the MathJax output. See the MathJax site (see: @@ -1636,14 +1636,14 @@ MATHJAX_FORMAT = HTML-CSS # The default value is: https://cdn.jsdelivr.net/npm/mathjax@2. # This tag requires that the tag USE_MATHJAX is set to YES. -MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest +MATHJAX_RELPATH = https://cdn.jsdelivr.net/npm/mathjax@2 # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example # MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols # This tag requires that the tag USE_MATHJAX is set to YES. -MATHJAX_EXTENSIONS = +MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols # The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces # of code that will be used on startup of the MathJax code. See the MathJax site diff --git a/docs/doxygen/ie_plugin_api.config b/docs/doxygen/ie_plugin_api.config index 9c933ff249f..1384184a417 100644 --- a/docs/doxygen/ie_plugin_api.config +++ b/docs/doxygen/ie_plugin_api.config @@ -60,3 +60,5 @@ PREDEFINED = "INFERENCE_ENGINE_API=" \ "IE_SUPPRESS_DEPRECATED_END_WIN=" \ "IE_THREAD=IE_THREAD_TBB" \ "NGRAPH_RTTI_DECLARATION=" + +WARN_LOGFILE = @DOCS_BUILD_DIR@/ie_plugin_api.log diff --git a/docs/doxygen/ie_py_api.config b/docs/doxygen/ie_py_api.config index f8993142120..fd2005b800e 100644 --- a/docs/doxygen/ie_py_api.config +++ b/docs/doxygen/ie_py_api.config @@ -33,3 +33,5 @@ INPUT = "@PYTHON_API_OUT@" HTML_OUTPUT = ie_python_api GENERATE_TAGFILE = "@DOCS_BUILD_DIR@/ie_python_api.tag" + +WARN_LOGFILE = @DOCS_BUILD_DIR@/ie_py_api.log diff --git a/docs/doxygen/linkchecker_filter.yaml b/docs/doxygen/linkchecker_filter.yaml deleted file mode 100644 index fc5e941c82d..00000000000 --- a/docs/doxygen/linkchecker_filter.yaml +++ /dev/null @@ -1,4 +0,0 @@ -exclude_links: - - '.*?\@ref omz.*' - - '.*?\@ref pot.*' - - '.*?\@ref workbench.*' diff --git a/docs/doxygen/log.py b/docs/doxygen/log.py new file mode 100644 index 00000000000..bfd10f02480 --- /dev/null +++ b/docs/doxygen/log.py @@ -0,0 +1,68 @@ +import argparse +import os +import re + +def parse_arguments(): + parser = argparse.ArgumentParser() + parser.add_argument('--log', type=str, required=True, default=None, help='Path to doxygen log file') + parser.add_argument('--ignore-list', type=str, required=False, + default=os.path.join(os.path.abspath(os.path.dirname(__file__)),'doxygen-ignore.txt'), + help='Path to doxygen ignore list') + parser.add_argument('--strip', type=str, required=False, default=os.path.abspath('../../'), + help='Strip from warning paths') + parser.add_argument('--exclude-links', nargs='+', type=str, required=False, default=[], help='Markdown links to be excluded') + return parser.parse_args() + + +def strip_path(path, strip): + """Strip `path` components ends on `strip` + """ + path = path.replace('\\', '/') + if path.endswith('.md') or path.endswith('.tag'): + strip = os.path.join(strip, 'build/docs').replace('\\', '/') + '/' + else: + strip = strip.replace('\\', '/') + '/' + return path.split(strip)[-1] + + +def is_excluded_link(warning, exclude_links): + if 'unable to resolve reference to' in warning: + ref = re.findall(r"'(.*?)'", warning) + if ref: + ref = ref[0] + for link in exclude_links: + reg = re.compile(link) + if re.match(reg, ref): + return True + return False + + +def parse(log, ignore_list, strip, exclude_links): + found_errors = [] + with open(ignore_list, 'r') as f: + ignore_list = f.read().splitlines() + with open(log, 'r') as f: + log = f.read().splitlines() + for line in log: + if 'warning:' in line: + path, warning = list(map(str.strip, line.split('warning:'))) + path, line_num = path[:-1].rsplit(':', 1) + path = strip_path(path, strip) + if path in ignore_list or is_excluded_link(warning, exclude_links): + continue + else: + found_errors.append('{path} {warning} line: {line_num}'.format(path=path, + warning=warning, + line_num=line_num)) + if found_errors: + print('\n'.join(found_errors)) + exit(1) + + +def main(): + args = parse_arguments() + parse(args.log, args.ignore_list, args.strip, args.exclude_links) + + +if __name__ == '__main__': + main() diff --git a/docs/doxygen/ngraph_cpp_api.config b/docs/doxygen/ngraph_cpp_api.config index 0fba49bb28c..de55a6f36a9 100644 --- a/docs/doxygen/ngraph_cpp_api.config +++ b/docs/doxygen/ngraph_cpp_api.config @@ -19,3 +19,5 @@ INPUT = "@NGRAPH_DIR@/core/include/" \ HTML_OUTPUT = ngraph_cpp_api GENERATE_TAGFILE = "@DOCS_BUILD_DIR@/ngraph_cpp_api.tag" + +WARN_LOGFILE = @DOCS_BUILD_DIR@/ngraph_cpp_api.log diff --git a/docs/doxygen/ngraph_py_api.config b/docs/doxygen/ngraph_py_api.config index 0f5c087e3d8..abf5a5d2093 100644 --- a/docs/doxygen/ngraph_py_api.config +++ b/docs/doxygen/ngraph_py_api.config @@ -20,3 +20,5 @@ INPUT = "@NGRAPH_PY_DIR@" HTML_OUTPUT = ngraph_python_api PYTHON_DOCSTRING = NO + +WARN_LOGFILE = @DOCS_BUILD_DIR@/ngraph_python_api.log