From 776005749c0864ce0bdf2d3d5b78ba122645bddc Mon Sep 17 00:00:00 2001 From: Ilya Lavrenov Date: Tue, 1 Dec 2020 06:33:36 +0300 Subject: [PATCH] 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 --- cmake/features.cmake | 2 ++ docs/CMakeLists.txt | 25 +++++++++++++++++-------- docs/doxygen/ie_c_api.config | 2 +- docs/doxygen/ie_docs.config | 2 +- docs/doxygen/ie_plugin_api.config | 2 +- docs/doxygen/ie_py_api.config | 2 +- docs/doxygen/ngraph_cpp_api.config | 9 +++++---- docs/doxygen/ngraph_py_api.config | 6 +++--- docs/ops/activation/HSwish_4.md | 6 +++--- docs/ops/activation/SoftPlus_4.md | 6 +++--- docs/ops/pooling/AvgPool_1.md | 6 +++--- docs/ops/pooling/MaxPool_1.md | 6 +++--- inference-engine/include/ie_version.hpp | 3 +++ 13 files changed, 46 insertions(+), 31 deletions(-) diff --git a/cmake/features.cmake b/cmake/features.cmake index 63fa5be1d37..a99de90445a 100644 --- 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") diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 94dd48230aa..595c6e7138a 100644 --- 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 diff --git a/docs/doxygen/ie_c_api.config b/docs/doxygen/ie_c_api.config index 1f56478070e..541a21efe54 100644 --- 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 \ diff --git a/docs/doxygen/ie_docs.config b/docs/doxygen/ie_docs.config index 4e70ad83028..c6264fac258 100644 --- 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 diff --git a/docs/doxygen/ie_plugin_api.config b/docs/doxygen/ie_plugin_api.config index 5f2a53fe140..9c933ff249f 100644 --- 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@" diff --git a/docs/doxygen/ie_py_api.config b/docs/doxygen/ie_py_api.config index a887aea1c7d..f8993142120 100644 --- 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* \ diff --git a/docs/doxygen/ngraph_cpp_api.config b/docs/doxygen/ngraph_cpp_api.config index e5ec4fc8212..0fba49bb28c 100644 --- 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" diff --git a/docs/doxygen/ngraph_py_api.config b/docs/doxygen/ngraph_py_api.config index ee93402792e..0f5c087e3d8 100644 --- 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 diff --git a/docs/ops/activation/HSwish_4.md b/docs/ops/activation/HSwish_4.md index a2bf8407ea3..bf572c39f43 100644 --- 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). diff --git a/docs/ops/activation/SoftPlus_4.md b/docs/ops/activation/SoftPlus_4.md index 112faa28730..135c4cb9dcc 100644 --- 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. diff --git a/docs/ops/pooling/AvgPool_1.md b/docs/ops/pooling/AvgPool_1.md index dfa04c476b0..b8f0ecb2f31 100644 --- 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** diff --git a/docs/ops/pooling/MaxPool_1.md b/docs/ops/pooling/MaxPool_1.md index 6e705e49a22..e730b7892ca 100644 --- 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** diff --git a/inference-engine/include/ie_version.hpp b/inference-engine/include/ie_version.hpp index b81a7c38cc7..e3773d6e1f1 100644 --- 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 { /**