diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index bcc579d..eecbb41 100644 --- a/.gitlab-ci.yml +++ b/.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}" diff --git a/setup.cfg b/setup.cfg index dba698c..3a460f6 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,6 +1,6 @@ [metadata] name = esp-docs -version = 1.0.2 +version = 1.1.0 author = Espressif author_email = marius.vikhammer@espressif.com description = Documentation building package used at Espressif diff --git a/src/esp_docs/build_docs.py b/src/esp_docs/build_docs.py index 08abaed..e819073 100755 --- a/src/esp_docs/build_docs.py +++ b/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), diff --git a/test/build_tests/doxygen_warning/Doxyfile b/test/build_tests/doxygen_warning/Doxyfile new file mode 100644 index 0000000..9766a8c --- /dev/null +++ b/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 diff --git a/test/build_tests/doxygen_warning/api_no_warning/api/my_api.h b/test/build_tests/doxygen_warning/api_no_warning/api/my_api.h new file mode 100644 index 0000000..fb22e99 --- /dev/null +++ b/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); \ No newline at end of file diff --git a/test/build_tests/doxygen_warning/api_warning/api/my_api.h b/test/build_tests/doxygen_warning/api_warning/api/my_api.h new file mode 100644 index 0000000..cc8a321 --- /dev/null +++ b/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); \ No newline at end of file diff --git a/test/build_tests/doxygen_warning/build.sh b/test/build_tests/doxygen_warning/build.sh new file mode 100755 index 0000000..cd6ce46 --- /dev/null +++ b/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 diff --git a/test/build_tests/doxygen_warning/conf_common.py b/test/build_tests/doxygen_warning/conf_common.py new file mode 100644 index 0000000..03f3b74 --- /dev/null +++ b/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' diff --git a/test/build_tests/doxygen_warning/en/conf.py b/test/build_tests/doxygen_warning/en/conf.py new file mode 100644 index 0000000..7e71618 --- /dev/null +++ b/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' diff --git a/test/build_tests/doxygen_warning/en/index.rst b/test/build_tests/doxygen_warning/en/index.rst new file mode 100644 index 0000000..ba0138b --- /dev/null +++ b/test/build_tests/doxygen_warning/en/index.rst @@ -0,0 +1,4 @@ +ESP-Docs Doxygen Warning Test +============================= + +.. include-build-file:: inc/my_api.inc