Documentation fixes (#3418)

* Fixed documentation build when paths contain spaces * ops math formula fix * Fixed typo in * Added more dependencies for openvino_docs * Improvements Co-authored-by: Nikolay Tyukaev <ntyukaev_lo@jenkins.inn.intel.com>
2020-12-01 06:33:36 +03:00 · 2020-12-01 06:33:36 +03:00 · 776005749c
commit 776005749c
parent 9b203938bd
13 changed files with 46 additions and 31 deletions
--- a/cmake/features.cmake
+++ b/cmake/features.cmake
@ -64,3 +64,5 @@ ie_option_enum(SELECTIVE_BUILD "Enable OpenVINO conditional compilation or stati
 In case SELECTIVE_BUILD is enabled, the SELECTIVE_BUILD_STAT variable should contain the path to the collected InelSEAPI statistics. \
 Usage: -DSELECTIVE_BUILD=ON -DSELECTIVE_BUILD_STAT=/path/*.csv" OFF
               ALLOWED_VALUES ON OFF COLLECT)
+
+set(LINKCHECKER_PY "" CACHE FILEPATH "Path to linkchecker.py for documentation check")
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@ -62,7 +62,7 @@ function(build_docs)
    set(PLUGIN_API_DIR "${DOCS_BUILD_DIR}/IE_PLUGIN_DG")
    set(NGRAPH_DIR "${OpenVINO_MAIN_SOURCE_DIR}/ngraph")
    set(NGRAPH_PY_DIR "${NGRAPH_DIR}/python/src/ngraph/")
-    set(NGRAPH_CPP_DIR "${NGRAPH_DIR}/core/include/ ${NGRAPH_DIR}/frontend/onnx_import/include")
+    set(NGRAPH_CPP_DIR "${NGRAPH_DIR}/core/include/" "${NGRAPH_DIR}/frontend/onnx_import/include")

    # Preprocessing scripts
    set(DOXY_MD_FILTER "${DOXYGEN_DIR}/doxy_md_filter.py")
@ -111,7 +111,7 @@ function(build_docs)

    # Tables of contents
    configure_file(${NGRAPH_CPP_LAYOUT_SOURCE} ${NGRAPH_CPP_LAYOUT_BUILD} @ONLY)
-    configure_file(${NGRAPH_PY_LAYOUT_SOURCE} ${NGRAPG_PY_LAYOUT_BUILD} @ONLY)
+    configure_file(${NGRAPH_PY_LAYOUT_SOURCE} ${NGRAPH_PY_LAYOUT_BUILD} @ONLY)
    configure_file(${IE_LAYOUT_SOURCE} ${IE_LAYOUT_BUILD} @ONLY)
    configure_file(${C_LAYOUT_SOURCE} ${C_LAYOUT_BUILD} @ONLY)
    configure_file(${PY_LAYOUT_SOURCE} ${PY_LAYOUT_BUILD} @ONLY)
@ -192,7 +192,7 @@ function(build_docs)
    # Plugin API

    add_custom_target(plugin_api
-                      DEPENDS ie_docs
+                      DEPENDS ngraph_cpp_api ie_docs
                      COMMAND ${DOXYGEN_EXECUTABLE} ${PLUGIN_CONFIG_BUILD}
                      WORKING_DIRECTORY ${DOCS_BUILD_DIR}
                      COMMENT "Generating Plugin API Reference"
@ -205,14 +205,23 @@ function(build_docs)
                      COMMENT "Generating OpenVINO documentation"
                      VERBATIM)

-    add_custom_target(docs_check
-                      COMMAND ${Python3_EXECUTABLE} ${LINKCHECKER_EXECUTABLE} ${DOCS_BUILD_DIR}/html/ -f ${DOXYGEN_DIR}/linkchecker_filter.yaml --no_recursive -l ${DOCS_BUILD_DIR}
-                      COMMENT "Check links in generated documentation"
-                      VERBATIM)
-
    set_target_properties(openvino_docs ie_docs c_api py_api preprocess_docs plugin_api
+                          ngraph_py_api ngraph_cpp_api
                          PROPERTIES FOLDER docs)

+    # added linkcheker
+
+    if(EXISTS "${LINKCHECKER_PY}")
+        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}"
+                            COMMENT "Check links in generated documentation"
+                            WORKING_DIRECTORY "${DOCS_BUILD_DIR}"
+                            VERBATIM)
+        set_target_properties(docs_check PROPERTIES FOLDER docs)
+    endif()
+
    find_program(browser NAMES xdg-open)
    if(browser)
        add_custom_target(ie_docs_open
--- a/docs/doxygen/ie_c_api.config
+++ b/docs/doxygen/ie_c_api.config
@ -1,4 +1,4 @@
-@INCLUDE = @IE_CONFIG_BUILD@
+@INCLUDE = "@IE_CONFIG_BUILD@"

 EXCLUDE_SYMBOLS        = INFERENCE_ENGINE_C_API_EXTERN \
                         INFERENCE_ENGINE_C_API \
--- a/docs/doxygen/ie_docs.config
+++ b/docs/doxygen/ie_docs.config
@ -735,7 +735,7 @@ FILE_VERSION_FILTER    =
 # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
 # tag is left empty.

-LAYOUT_FILE            = @IE_LAYOUT_BUILD@
+LAYOUT_FILE            = "@IE_LAYOUT_BUILD@"

 # The CITE_BIB_FILES tag can be used to specify one or more bib files containing
 # the reference definitions. This must be a list of .bib files. The .bib
--- a/docs/doxygen/ie_plugin_api.config
+++ b/docs/doxygen/ie_plugin_api.config
@ -1,4 +1,4 @@
-@INCLUDE = @IE_CONFIG_BUILD@
+@INCLUDE = "@IE_CONFIG_BUILD@"

 LAYOUT_FILE            = "@PLUGIN_LAYOUT_BUILD@"

--- a/docs/doxygen/ie_py_api.config
+++ b/docs/doxygen/ie_py_api.config
@ -1,4 +1,4 @@
-@INCLUDE = @IE_CONFIG_BUILD@
+@INCLUDE = "@IE_CONFIG_BUILD@"

 EXCLUDE_SYMBOLS        = ie_api::BlobBuffer \
                         *impl* \
--- a/docs/doxygen/ngraph_cpp_api.config
+++ b/docs/doxygen/ngraph_cpp_api.config
@ -1,4 +1,4 @@
-@INCLUDE = @IE_CONFIG_BUILD@
+@INCLUDE = "@IE_CONFIG_BUILD@"

 EXCLUDE_SYMBOLS        = 

@ -11,10 +11,11 @@ FILE_PATTERNS          = *.cpp \
                         *.hpp \
                         *.h

-LAYOUT_FILE            = @NGRAPH_CPP_LAYOUT_BUILD@
+LAYOUT_FILE            = "@NGRAPH_CPP_LAYOUT_BUILD@"

-INPUT                  = @NGRAPH_CPP_DIR@
+INPUT                  = "@NGRAPH_DIR@/core/include/" \
+                         "@NGRAPH_DIR@/frontend/onnx_import/include"

 HTML_OUTPUT            = ngraph_cpp_api

-GENERATE_TAGFILE       = @DOCS_BUILD_DIR@/ngraph_cpp_api.tag
+GENERATE_TAGFILE       = "@DOCS_BUILD_DIR@/ngraph_cpp_api.tag"
--- a/docs/doxygen/ngraph_py_api.config
+++ b/docs/doxygen/ngraph_py_api.config
@ -1,4 +1,4 @@
-@INCLUDE = @IE_CONFIG_BUILD@
+@INCLUDE = "@IE_CONFIG_BUILD@"

 PREDEFINED             =

@ -13,9 +13,9 @@ EXCLUDE_SYMBOLS        = ngraph::utils

 FILE_PATTERNS          = *.py

-LAYOUT_FILE            = @NGRAPH_PY_LAYOUT_BUILD@
+LAYOUT_FILE            = "@NGRAPH_PY_LAYOUT_BUILD@"

-INPUT                  = @NGRAPH_PY_DIR@
+INPUT                  = "@NGRAPH_PY_DIR@"

 HTML_OUTPUT            = ngraph_python_api

--- a/docs/ops/activation/HSwish_4.md
+++ b/docs/ops/activation/HSwish_4.md
@ -9,9 +9,9 @@
 **Detailed description**: For each element from the input tensor calculates corresponding
 element in the output tensor with the following formula: 

-    \f[
-    HSwish(x) = x \frac{min(max(x + 3, 0), 6)}{6}
-    \f]
+\f[
+HSwish(x) = x \frac{min(max(x + 3, 0), 6)}{6}
+\f]

 The HSwish operation is introduced in the following [article](https://arxiv.org/pdf/1905.02244.pdf).

--- a/docs/ops/activation/SoftPlus_4.md
+++ b/docs/ops/activation/SoftPlus_4.md
@ -9,9 +9,9 @@
 **Detailed description**: For each element from the input tensor calculates corresponding
 element in the output tensor with the following formula:

-    \f[
-    SoftPlus(x) = ln(e^{x} + 1.0)
-    \f]
+\f[
+SoftPlus(x) = ln(e^{x} + 1.0)
+\f]

 **Attributes**: *SoftPlus* operation has no attributes.

--- a/docs/ops/pooling/AvgPool_1.md
+++ b/docs/ops/pooling/AvgPool_1.md
@ -78,9 +78,9 @@

 **Mathematical Formulation**

-    \f[
-    output_{j} = \frac{\sum_{i = 0}^{n}x_{i}}{n}
-    \f]
+\f[
+output_{j} = \frac{\sum_{i = 0}^{n}x_{i}}{n}
+\f]

 **Example**

--- a/docs/ops/pooling/MaxPool_1.md
+++ b/docs/ops/pooling/MaxPool_1.md
@ -70,9 +70,9 @@

 **Mathematical Formulation**

-    \f[
-    output_{j} = MAX\{ x_{0}, ... x_{i}\}
-    \f]
+\f[
+output_{j} = MAX\{ x_{0}, ... x_{i}\}
+\f]

 **Example**

--- a/inference-engine/include/ie_version.hpp
+++ b/inference-engine/include/ie_version.hpp
@ -11,6 +11,9 @@

 #include "ie_api.h"

+/**
+ * @brief Inference Engine C++ API
+ */
 namespace InferenceEngine {

 /**