Merge branch 'bugfix/doxygen_error_fail_build' into 'master'

Doxygen warning should fail build

See merge request espressif/esp-docs!33

.gitlab-ci.yml

@@ -99,7 +99,7 @@ build_idf_docs_html:
     - .build_template
   variables:
     DOCS_DIR: $CI_PROJECT_DIR/esp-idf/docs
-    IDF_COMMIT_ID: 197be02748e5f7718d2eb4ff004c529d20e83b85
+    IDF_COMMIT_ID: 3faf5ba8f784f
   script:
       # add gitlab ssh key
     - cit_add_ssh_key "${GITLAB_KEY_PEM}"
@@ -119,7 +119,7 @@ build_idf_docs_pdf:
     - .build_template
   variables:
     DOCS_DIR: $CI_PROJECT_DIR/esp-idf/docs
-    IDF_COMMIT_ID: 197be02748e5f7718d2eb4ff004c529d20e83b85
+    IDF_COMMIT_ID: 3faf5ba8f784f
   script:
       # add gitlab ssh key
     - cit_add_ssh_key "${GITLAB_KEY_PEM}"

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = esp-docs
-version = 1.0.2
+version = 1.1.0
 author = Espressif
 author_email = [email protected]
 description = Documentation building package used at Espressif

src/esp_docs/build_docs.py

@@ -302,11 +302,22 @@ def call_build_docs(build_info):
 
         # Warnings are checked after each builder as logs are overwritten
         # check Doxygen warnings only if we actually have a doxyfile:
-        if os.path.isfile(os.path.join(build_info['doxyfile_dir'], 'Doxyfile_common')):
+        def has_doxyfile(doxyfile_dir):
+            if os.path.isfile(os.path.join(doxyfile_dir, 'Doxyfile')):
+                return True
+            elif os.path.isfile(os.path.join('doxygen', 'Doxyfile')):  # kept for backwards compatibility
+                return True
+            else:
+                return False
+
+        if has_doxyfile(build_info['doxyfile_dir']):
             ret += check_docs(build_info['language'], build_info['target'],
                               log_file=os.path.join(build_info['build_dir'], DXG_WARN_LOG),
                               known_warnings_file=DXG_KNOWN_WARNINGS,
                               out_sanitized_log_file=os.path.join(build_info['build_dir'], DXG_SANITIZED_LOG))
+        else:
+            print('No Doxyfile found, skipping check of doxygen errors')
+
         # check Sphinx warnings:
         ret += check_docs(build_info['language'], build_info['target'],
                           log_file=os.path.join(build_info['build_dir'], SPHINX_WARN_LOG),

test/build_tests/doxygen_warning/Doxyfile

@@ -0,0 +1,56 @@
+# This is Doxygen configuration file
+#
+# Doxygen provides over 260 configuration statements
+# To make this file easier to follow,
+# it contains only statements that are non-default
+#
+# NOTE:
+# It is recommended not to change defaults unless specifically required
+# Test any changes how they affect generated documentation
+# Make sure that correct warnings are generated to flag issues with documented code
+#
+# For the complete list of configuration statements see:
+# http://doxygen.nl/manual/config.html
+
+
+PROJECT_NAME = "Esp-docs simple example"
+
+## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
+## to automatically generate API reference list files header_file.inc
+## These files are placed in '_inc' directory
+## and used to include in API reference documentation
+
+INPUT = \
+    $(PROJECT_PATH)/api/my_api.h
+
+
+## Get warnings for functions that have no documentation for their parameters or return value
+##
+WARN_NO_PARAMDOC = YES
+
+## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files
+##
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = \
+    $(ENV_DOXYGEN_DEFINES)
+
+## Do not complain about not having dot
+##
+HAVE_DOT = NO
+
+## Generate XML that is required for Breathe
+##
+GENERATE_XML    = YES
+XML_OUTPUT      = xml
+
+GENERATE_HTML   = NO
+HAVE_DOT        = NO
+GENERATE_LATEX  = NO
+GENERATE_MAN    = YES
+GENERATE_RTF    = NO
+
+## Skip distracting progress messages
+##
+QUIET = YES

test/build_tests/doxygen_warning/api_no_warning/api/my_api.h

@@ -0,0 +1,16 @@
+#pragma once
+
+#define BIG_NUMBER 124356
+
+/**
+ * @brief   Returns a random number inside a range
+ *
+ *
+ * @param[in]   min   Lower end of the range
+ * @param[in]   max   Upper end of the range
+ *
+ * @note    Not cryptographically secure
+ *
+ * @return      random integer
+ */
+int random_number(int min, int max);

test/build_tests/doxygen_warning/api_warning/api/my_api.h

@@ -0,0 +1,15 @@
+#pragma once
+
+#define BIG_NUMBER 124356
+
+/**
+ * @brief   Returns a random number inside a range
+ *
+ *
+ * @param[in]   min   Lower end of the range
+ *
+ * @note    Not cryptographically secure
+ *
+ * @return      random integer
+ */
+int random_number(int min, int max);

test/build_tests/doxygen_warning/build.sh

@@ -0,0 +1,8 @@
+if build-docs --project-path api_warning -l en; then
+    echo "build-docs should have failed with doxygen warning"
+    exit 1
+else
+    echo "build-docs failed with warning (expected result)"
+fi
+
+build-docs --project-path api_no_warning -l en

test/build_tests/doxygen_warning/conf_common.py

@@ -0,0 +1,18 @@
+from esp_docs.conf_docs import *  # noqa: F403,F401
+
+extensions += [  # Needed as a trigger for running doxygen
+               'esp_docs.esp_extensions.dummy_build_system',
+               'esp_docs.esp_extensions.run_doxygen',
+               ]
+
+languages = ['en', 'zh_CN']
+
+# link roles config
+github_repo = 'espressif/esp-docs'
+
+# context used by sphinx_idf_theme
+html_context['github_user'] = 'espressif'
+html_context['github_repo'] = 'esp-docs'
+
+# Extra options required by sphinx_idf_theme
+project_slug = 'esp-docs'

test/build_tests/doxygen_warning/en/conf.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+#
+# English Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('../'))
+    from conf_common import *  # noqa: F403,F401
+
+# General information about the project.
+project = u'ESP-Docs'
+copyright = u'2016 - 2021, Espressif Systems (Shanghai) Co., Ltd'
+pdf_title = u'ESP-Docs Example Guide'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'

test/build_tests/doxygen_warning/en/index.rst

@@ -0,0 +1,4 @@
+ESP-Docs Doxygen Warning Test
+=============================
+
+.. include-build-file:: inc/my_api.inc