doc updates (#3437)

* doc updates

* delete linkchecker_filter.yaml

* parse doxygen log

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}"
+                            COMMAND ${Python3_EXECUTABLE} "${LINKCHECKER}" -v "${DOCS_BUILD_DIR}/html/"
-                                    "${DOCS_BUILD_DIR}/html/" -f "${DOXYGEN_DIR}/linkchecker_filter.yaml"
-                                    --no_recursive -l "${DOCS_BUILD_DIR}"
                             COMMENT "Check links in generated documentation"
                             WORKING_DIRECTORY "${DOCS_BUILD_DIR}"
                             VERBATIM)

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

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

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

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

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

docs/doxygen/linkchecker_filter.yaml

@@ -1,4 +0,0 @@
-exclude_links:
-  - '.*?\@ref omz.*'
-  - '.*?\@ref pot.*'
-  - '.*?\@ref workbench.*'

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()

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

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