Merge branch 'bugfix/update_docs_build' into 'master'

Resolve issues with Doxyfile causing newer Doxygen versions to fail

Closes DOC-12663

See merge request adf/esp-adf-internal!1462

Author: krzychb

.gitignore

@@ -57,4 +57,6 @@ coverage_report/
 
 .vscode
 
-**/.cache/
+**/.cache/
+
+docs/venv/

.gitlab/ci/docs.yml

@@ -65,7 +65,6 @@
   script:
     - pip install -r docs/requirements.txt
     - cd $DOCS_DIR
-    - mkdir -p $ADF_PATH/docs/_build/${DOCLANG}/generic/inc
     - build-docs -bs $DOC_BUILDERS -l $DOCLANG build
     - ./check_lang_folder_sync.sh
     - echo "ESP-ADF Guide preview available at $CI_JOB_URL/artifacts/file/docs/_build/$DOCLANG/generic/html/index.html"

components/audio_recorder/include/audio_recorder.h

@@ -49,7 +49,7 @@ typedef struct {
     /**
     * @brief Audio recorder event type
     */
-    enum {
+    enum audio_recorder_event_type_t {
         AUDIO_REC_WAKEUP_START = -100, /*!< Wakeup start */
         AUDIO_REC_WAKEUP_END,          /*!< Wakeup stop */
         AUDIO_REC_VAD_START,           /*!< Vad start */

docs/Doxyfile

@@ -8,12 +8,17 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('..'))
 
+doxygen_version = run_cmd_get_output('doxygen --version')
+print(f"Doxygen version: {doxygen_version}")
+
 builddir = '_build'
 if 'BUILDDIR' in os.environ:
     builddir = os.environ['BUILDDIR']
 
 # Generate 'kconfig.inc' file from components' Kconfig files
-kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir)
+kconfig_inc_folder = f'{builddir}/inc/'
+os.makedirs(kconfig_inc_folder, exist_ok=True)
+kconfig_inc_path = kconfig_inc_folder + 'kconfig.inc'
 os.system('python ../gen-kconfig-doc.py > ' + kconfig_inc_path + '.in')
 copy_if_modified(kconfig_inc_path + '.in', kconfig_inc_path)
 
@@ -22,8 +27,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions += ['link-roles',
-               'sphinx_copybutton',
+extensions += ['sphinx_copybutton',
                'sphinxcontrib.wavedrom',
                'esp_docs.esp_extensions.dummy_build_system',
                'esp_docs.esp_extensions.run_doxygen',

docs/check_doc_warnings.sh

@@ -27,7 +27,7 @@ Ringbuffer is designed in addition to use as a data buffer, also used to connect
 Application Example
 -------------------
 
-In most of ESP-ADF :adf:`examples` connecting of Elements with Ringbuffers is done "behind the scenes" by a function :cpp:func:`audio_pipeline_link`. To see this operation exposed check :example:`player/pipeline_sdcard_mp3_control` example.
+In most of ESP-ADF :project:`examples` connecting of Elements with Ringbuffers is done "behind the scenes" by a function :cpp:func:`audio_pipeline_link`. To see this operation exposed check :example:`player/pipeline_sdcard_mp3_control` example.
 
 
 API Reference

docs/conf_common.py

@@ -29,7 +29,7 @@ Setting up the speech recognition application to detect a wakeup word may be don
     }
 
 
-Configuration and use of particular elements is demonstrated in several :adf:`examples <examples>` linked to elsewhere in this documentation. What may need clarification is use of the **Filter** and the **RAW stream**. The filter is used to adjust the sample rate of the I2S stream to match the sample rate of the speech recognition model. The RAW stream is the way to feed the audio input to the model.
+Configuration and use of particular elements is demonstrated in several :project:`examples <examples>` linked to elsewhere in this documentation. What may need clarification is use of the **Filter** and the **RAW stream**. The filter is used to adjust the sample rate of the I2S stream to match the sample rate of the speech recognition model. The RAW stream is the way to feed the audio input to the model.
 
 The above introduction is the primary guidance. ESP-ADF offers users a more flexible and convenient module, namely the :doc:`audio recorder <audio_recorder>`, which is strongly recommended for use.
 

docs/docs_common.mk

@@ -162,7 +162,7 @@ Application Example
 Tone Stream
 -----------
 
-The tone stream reads the data generated by :adf_file:`tools/audio_tone/mk_audio_tone.py`. It only supports the ``AUDIO_STREAM_READER`` type.
+The tone stream reads the data generated by :project_file:`tools/audio_tone/mk_audio_tone.py`. It only supports the ``AUDIO_STREAM_READER`` type.
 
 
 Application Example
@@ -179,7 +179,7 @@ Application Example
 Flash-Embedding Stream
 ----------------------
 
-The flash-embedding stream reads the data generated by :adf_file:`tools/audio_tone/mk_embed_flash.py`. It only supports the ``AUDIO_STREAM_READER`` type.
+The flash-embedding stream reads the data generated by :project_file:`tools/audio_tone/mk_embed_flash.py`. It only supports the ``AUDIO_STREAM_READER`` type.
 
 
 Application Example