2018-03-14 23:47:57 +00:00
|
|
|
# -*- coding: utf-8 -*-
|
|
|
|
#
|
2021-08-24 00:56:48 +00:00
|
|
|
# Common (non-language-specific) configuration for Sphinx
|
2018-03-14 23:47:57 +00:00
|
|
|
#
|
|
|
|
# This file is imported from a language-specific conf.py (ie en/conf.py or
|
|
|
|
# zh_CN/conf.py)
|
2021-08-24 00:56:48 +00:00
|
|
|
|
|
|
|
# type: ignore
|
|
|
|
# pylint: disable=wildcard-import
|
|
|
|
# pylint: disable=undefined-variable
|
2018-03-14 23:47:57 +00:00
|
|
|
|
2021-01-11 11:49:21 +00:00
|
|
|
from __future__ import print_function, unicode_literals
|
|
|
|
|
2019-11-28 21:56:53 +00:00
|
|
|
import os.path
|
2021-11-09 09:11:01 +00:00
|
|
|
import re
|
2020-02-19 04:24:59 +00:00
|
|
|
|
2021-08-24 00:56:48 +00:00
|
|
|
from esp_docs.conf_docs import * # noqa: F403,F401
|
2019-11-22 05:58:04 +00:00
|
|
|
|
2021-08-24 09:40:11 +00:00
|
|
|
if os.environ.get('IDF_PATH') is None:
|
|
|
|
raise RuntimeError('IDF_PATH should be set, run export.sh before building docs')
|
|
|
|
|
2020-04-30 08:55:12 +00:00
|
|
|
BT_DOCS = ['api-guides/blufi.rst',
|
|
|
|
'api-guides/esp-ble-mesh/**',
|
2021-10-25 12:15:13 +00:00
|
|
|
'api-reference/bluetooth/bt_le.rst',
|
|
|
|
'api-reference/bluetooth/esp_bt_defs.rst',
|
|
|
|
'api-reference/bluetooth/esp_bt_device.rst',
|
|
|
|
'api-reference/bluetooth/esp_bt_main.rst',
|
|
|
|
'api-reference/bluetooth/bt_common.rst',
|
|
|
|
'api-reference/bluetooth/controller_vhci.rst',
|
|
|
|
'api-reference/bluetooth/esp_gap_ble.rst',
|
|
|
|
'api-reference/bluetooth/esp_gatt_defs.rst',
|
|
|
|
'api-reference/bluetooth/esp_gatts.rst',
|
|
|
|
'api-reference/bluetooth/esp_gattc.rst',
|
|
|
|
'api-reference/bluetooth/esp_blufi.rst',
|
|
|
|
'api-reference/bluetooth/esp-ble-mesh.rst',
|
|
|
|
'api-reference/bluetooth/index.rst',
|
|
|
|
'api-reference/bluetooth/nimble/index.rst']
|
|
|
|
|
|
|
|
CLASSIC_BT_DOCS = ['api-reference/bluetooth/classic_bt.rst',
|
|
|
|
'api-reference/bluetooth/esp_a2dp.rst',
|
|
|
|
'api-reference/bluetooth/esp_avrc.rst',
|
2022-03-23 13:25:44 +00:00
|
|
|
'api-reference/bluetooth/esp_hidd.rst',
|
2022-05-18 07:48:21 +00:00
|
|
|
'api-reference/bluetooth/esp_l2cap_bt.rst',
|
2022-05-28 07:20:42 +00:00
|
|
|
'api-reference/bluetooth/esp_sdp.rst',
|
2021-10-25 12:15:13 +00:00
|
|
|
'api-reference/bluetooth/esp_hf_defs.rst',
|
|
|
|
'api-reference/bluetooth/esp_hf_client.rst',
|
|
|
|
'api-reference/bluetooth/esp_hf_ag.rst',
|
|
|
|
'api-reference/bluetooth/esp_spp.rst',
|
|
|
|
'api-reference/bluetooth/esp_gap_bt.rst']
|
2020-04-30 08:55:12 +00:00
|
|
|
|
2021-11-09 09:11:01 +00:00
|
|
|
WIFI_DOCS = ['api-guides/wifi.rst',
|
|
|
|
'api-guides/wifi-security.rst',
|
|
|
|
'api-guides/wireshark-user-guide.rst']
|
|
|
|
|
2021-07-29 03:20:52 +00:00
|
|
|
COEXISTENCE_DOCS = ['api-guides/coexist.rst']
|
|
|
|
|
2020-04-30 08:55:12 +00:00
|
|
|
SDMMC_DOCS = ['api-reference/peripherals/sdmmc_host.rst',
|
|
|
|
'api-reference/peripherals/sd_pullup_requirements.rst']
|
|
|
|
|
2021-01-11 11:49:21 +00:00
|
|
|
SDIO_SLAVE_DOCS = ['api-reference/peripherals/sdio_slave.rst',
|
|
|
|
'api-reference/protocols/esp_sdio_slave_protocol.rst']
|
2020-04-30 08:55:12 +00:00
|
|
|
|
|
|
|
MCPWM_DOCS = ['api-reference/peripherals/mcpwm.rst']
|
|
|
|
|
2020-09-29 10:14:17 +00:00
|
|
|
DEDIC_GPIO_DOCS = ['api-reference/peripherals/dedic_gpio.rst']
|
|
|
|
|
2020-10-29 01:57:09 +00:00
|
|
|
PCNT_DOCS = ['api-reference/peripherals/pcnt.rst']
|
|
|
|
|
2021-11-09 09:11:01 +00:00
|
|
|
RMT_DOCS = ['api-reference/peripherals/rmt.rst']
|
|
|
|
|
2020-10-29 01:57:09 +00:00
|
|
|
DAC_DOCS = ['api-reference/peripherals/dac.rst']
|
|
|
|
|
2021-06-10 10:01:09 +00:00
|
|
|
TEMP_SENSOR_DOCS = ['api-reference/peripherals/temp_sensor.rst']
|
|
|
|
|
2020-10-29 01:57:09 +00:00
|
|
|
TOUCH_SENSOR_DOCS = ['api-reference/peripherals/touch_pad.rst']
|
|
|
|
|
|
|
|
SPIRAM_DOCS = ['api-guides/external-ram.rst']
|
|
|
|
|
2021-06-30 08:04:37 +00:00
|
|
|
USB_DOCS = ['api-reference/peripherals/usb_device.rst',
|
2021-08-31 06:14:04 +00:00
|
|
|
'api-reference/peripherals/usb_host.rst',
|
2021-04-28 08:38:24 +00:00
|
|
|
'api-guides/usb-otg-console.rst',
|
2021-01-27 02:12:58 +00:00
|
|
|
'api-guides/dfu.rst']
|
2020-08-18 09:51:32 +00:00
|
|
|
|
2021-03-21 19:32:24 +00:00
|
|
|
FTDI_JTAG_DOCS = ['api-guides/jtag-debugging/configure-ft2232h-jtag.rst']
|
|
|
|
|
2021-04-28 08:38:24 +00:00
|
|
|
USB_SERIAL_JTAG_DOCS = ['api-guides/jtag-debugging/configure-builtin-jtag.rst',
|
|
|
|
'api-guides/usb-serial-jtag-console.rst']
|
2021-03-21 19:32:24 +00:00
|
|
|
|
2022-02-21 10:43:02 +00:00
|
|
|
ULP_DOCS = ['api-reference/system/ulp.rst',
|
|
|
|
'api-reference/system/ulp_macros.rst',
|
|
|
|
'api-reference/system/ulp_instruction_set.rst']
|
2020-10-29 01:57:09 +00:00
|
|
|
|
2022-02-21 10:43:02 +00:00
|
|
|
RISCV_COPROC_DOCS = ['api-reference/system/ulp-risc-v.rst',]
|
2021-01-27 02:12:58 +00:00
|
|
|
|
2021-03-12 07:20:41 +00:00
|
|
|
XTENSA_DOCS = ['api-guides/hlinterrupts.rst',
|
|
|
|
'api-reference/system/perfmon.rst']
|
2020-10-29 01:57:09 +00:00
|
|
|
|
2021-05-24 07:08:00 +00:00
|
|
|
RISCV_DOCS = [] # type: list[str]
|
2020-10-29 01:57:09 +00:00
|
|
|
|
2022-02-16 02:22:46 +00:00
|
|
|
TWAI_DOCS = ['api-reference/peripherals/twai.rst']
|
|
|
|
|
|
|
|
SIGMADELTA_DOCS = ['api-reference/peripherals/sigmadelta.rst']
|
|
|
|
|
|
|
|
I2S_DOCS = ['api-reference/peripherals/i2s.rst']
|
|
|
|
|
2022-02-21 10:43:02 +00:00
|
|
|
ESP32_DOCS = ['api-reference/system/himem.rst',
|
2021-01-27 02:12:58 +00:00
|
|
|
'api-guides/romconsole.rst',
|
2020-04-30 08:55:12 +00:00
|
|
|
'api-reference/system/ipc.rst',
|
|
|
|
'security/secure-boot-v1.rst',
|
2020-04-06 14:42:52 +00:00
|
|
|
'api-reference/peripherals/secure_element.rst',
|
2020-10-29 01:57:09 +00:00
|
|
|
'api-reference/peripherals/dac.rst',
|
2021-11-09 09:11:01 +00:00
|
|
|
'hw-reference/esp32/**',
|
|
|
|
'api-guides/RF_calibration.rst'] + FTDI_JTAG_DOCS
|
2020-04-30 08:55:12 +00:00
|
|
|
|
2020-12-03 08:21:16 +00:00
|
|
|
ESP32S2_DOCS = ['hw-reference/esp32s2/**',
|
2020-05-05 16:39:22 +00:00
|
|
|
'api-guides/usb-console.rst',
|
2020-04-23 05:52:33 +00:00
|
|
|
'api-reference/peripherals/ds.rst',
|
2020-04-29 08:20:40 +00:00
|
|
|
'api-reference/peripherals/spi_slave_hd.rst',
|
2020-07-28 12:15:13 +00:00
|
|
|
'api-reference/peripherals/temp_sensor.rst',
|
2020-08-18 09:51:32 +00:00
|
|
|
'api-reference/system/async_memcpy.rst',
|
2021-11-09 09:11:01 +00:00
|
|
|
'api-reference/peripherals/touch_element.rst',
|
|
|
|
'api-guides/RF_calibration.rst'] + FTDI_JTAG_DOCS
|
2020-10-29 01:57:09 +00:00
|
|
|
|
2021-06-22 08:55:32 +00:00
|
|
|
ESP32S3_DOCS = ['hw-reference/esp32s3/**',
|
2021-09-16 06:04:45 +00:00
|
|
|
'api-reference/system/ipc.rst',
|
2021-11-09 09:11:01 +00:00
|
|
|
'api-guides/flash_psram_config.rst',
|
|
|
|
'api-guides/RF_calibration.rst']
|
2021-05-24 07:08:00 +00:00
|
|
|
|
2021-04-28 08:38:24 +00:00
|
|
|
# No JTAG docs for this one as it gets gated on SOC_USB_SERIAL_JTAG_SUPPORTED down below.
|
2021-11-09 09:11:01 +00:00
|
|
|
ESP32C3_DOCS = ['hw-reference/esp32c3/**',
|
|
|
|
'api-guides/RF_calibration.rst']
|
2020-04-30 08:55:12 +00:00
|
|
|
|
|
|
|
# format: {tag needed to include: documents to included}, tags are parsed from sdkconfig and peripheral_caps.h headers
|
|
|
|
conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
|
2021-11-09 09:11:01 +00:00
|
|
|
'SOC_WIFI_SUPPORTED':WIFI_DOCS,
|
2021-10-25 12:15:13 +00:00
|
|
|
'SOC_CLASSIC_BT_SUPPORTED':CLASSIC_BT_DOCS,
|
2021-07-29 03:20:52 +00:00
|
|
|
'SOC_SUPPORT_COEXISTENCE':COEXISTENCE_DOCS,
|
2020-04-30 08:55:12 +00:00
|
|
|
'SOC_SDMMC_HOST_SUPPORTED':SDMMC_DOCS,
|
|
|
|
'SOC_SDIO_SLAVE_SUPPORTED':SDIO_SLAVE_DOCS,
|
|
|
|
'SOC_MCPWM_SUPPORTED':MCPWM_DOCS,
|
2021-06-30 08:04:37 +00:00
|
|
|
'SOC_USB_OTG_SUPPORTED':USB_DOCS,
|
2021-04-28 08:38:24 +00:00
|
|
|
'SOC_USB_SERIAL_JTAG_SUPPORTED':USB_SERIAL_JTAG_DOCS,
|
2020-09-29 10:14:17 +00:00
|
|
|
'SOC_DEDICATED_GPIO_SUPPORTED':DEDIC_GPIO_DOCS,
|
2020-10-29 01:57:09 +00:00
|
|
|
'SOC_SPIRAM_SUPPORTED':SPIRAM_DOCS,
|
|
|
|
'SOC_PCNT_SUPPORTED':PCNT_DOCS,
|
2021-11-09 09:11:01 +00:00
|
|
|
'SOC_RMT_SUPPORTED':RMT_DOCS,
|
2021-04-06 13:56:27 +00:00
|
|
|
'SOC_DAC_SUPPORTED':DAC_DOCS,
|
2020-10-29 01:57:09 +00:00
|
|
|
'SOC_TOUCH_SENSOR_NUM':TOUCH_SENSOR_DOCS,
|
|
|
|
'SOC_ULP_SUPPORTED':ULP_DOCS,
|
2021-01-27 02:12:58 +00:00
|
|
|
'SOC_RISCV_COPROC_SUPPORTED':RISCV_COPROC_DOCS,
|
2021-02-23 01:31:29 +00:00
|
|
|
'SOC_DIG_SIGN_SUPPORTED':['api-reference/peripherals/ds.rst'],
|
|
|
|
'SOC_HMAC_SUPPORTED':['api-reference/peripherals/hmac.rst'],
|
2021-03-12 07:20:41 +00:00
|
|
|
'SOC_ASYNC_MEMCPY_SUPPORTED':['api-reference/system/async_memcpy.rst'],
|
2020-10-29 01:57:09 +00:00
|
|
|
'CONFIG_IDF_TARGET_ARCH_XTENSA':XTENSA_DOCS,
|
|
|
|
'CONFIG_IDF_TARGET_ARCH_RISCV':RISCV_DOCS,
|
2021-06-10 10:01:09 +00:00
|
|
|
'SOC_TEMP_SENSOR_SUPPORTED':TEMP_SENSOR_DOCS,
|
2022-02-16 02:22:46 +00:00
|
|
|
'SOC_TWAI_SUPPORTED':TWAI_DOCS,
|
|
|
|
'SOC_I2S_SUPPORTED':I2S_DOCS,
|
|
|
|
'SOC_SIGMADELTA_SUPPORTED':SIGMADELTA_DOCS,
|
2020-04-30 08:55:12 +00:00
|
|
|
'esp32':ESP32_DOCS,
|
2020-10-29 01:57:09 +00:00
|
|
|
'esp32s2':ESP32S2_DOCS,
|
2021-05-24 07:08:00 +00:00
|
|
|
'esp32s3':ESP32S3_DOCS,
|
2020-10-29 01:57:09 +00:00
|
|
|
'esp32c3':ESP32C3_DOCS}
|
2020-02-03 06:38:45 +00:00
|
|
|
|
2021-08-24 00:56:48 +00:00
|
|
|
extensions += ['sphinx_copybutton',
|
2022-04-29 06:42:35 +00:00
|
|
|
'sphinxcontrib.wavedrom',
|
2021-08-24 00:56:48 +00:00
|
|
|
# Note: order is important here, events must
|
|
|
|
# be registered by one extension before they can be
|
|
|
|
# connected to another extension
|
|
|
|
'esp_docs.idf_extensions.build_system',
|
|
|
|
'esp_docs.idf_extensions.esp_err_definitions',
|
|
|
|
'esp_docs.idf_extensions.gen_toolchain_links',
|
|
|
|
'esp_docs.idf_extensions.gen_defines',
|
|
|
|
'esp_docs.idf_extensions.gen_version_specific_includes',
|
|
|
|
'esp_docs.idf_extensions.kconfig_reference',
|
|
|
|
'esp_docs.idf_extensions.gen_idf_tools_links',
|
|
|
|
'esp_docs.esp_extensions.run_doxygen',
|
|
|
|
]
|
|
|
|
|
2022-04-29 06:42:35 +00:00
|
|
|
# Use wavedrompy as backend, insted of wavedrom-cli
|
|
|
|
render_using_wavedrompy = True
|
|
|
|
|
2021-08-24 00:56:48 +00:00
|
|
|
# link roles config
|
|
|
|
github_repo = 'espressif/esp-idf'
|
2018-03-14 23:47:57 +00:00
|
|
|
|
2021-08-24 00:56:48 +00:00
|
|
|
# context used by sphinx_idf_theme
|
|
|
|
html_context['github_user'] = 'espressif'
|
2021-08-24 09:40:11 +00:00
|
|
|
html_context['github_repo'] = 'esp-idf'
|
2018-03-14 23:47:57 +00:00
|
|
|
|
2020-02-19 04:24:59 +00:00
|
|
|
# Extra options required by sphinx_idf_theme
|
|
|
|
project_slug = 'esp-idf'
|
|
|
|
versions_url = 'https://dl.espressif.com/dl/esp-idf/idf_versions.js'
|
|
|
|
|
2022-01-20 07:49:48 +00:00
|
|
|
idf_targets = ['esp32', 'esp32s2', 'esp32s3', 'esp32c3', 'esp32c2']
|
2020-02-19 04:24:59 +00:00
|
|
|
languages = ['en', 'zh_CN']
|
|
|
|
|
2021-04-09 03:57:03 +00:00
|
|
|
google_analytics_id = os.environ.get('CI_GOOGLE_ANALYTICS_ID', None)
|
2021-04-06 03:56:11 +00:00
|
|
|
|
2021-08-24 00:56:48 +00:00
|
|
|
project_homepage = 'https://github.com/espressif/esp-idf'
|
2021-11-12 09:20:03 +00:00
|
|
|
|
2022-04-28 07:59:03 +00:00
|
|
|
linkcheck_anchors = False
|
|
|
|
|
|
|
|
linkcheck_exclude_documents = ['index', # several false positives due to the way we link to different sections
|
|
|
|
'api-reference/protocols/esp_local_ctrl', # Fails due to `https://<mdns-hostname>.local`
|
|
|
|
'api-reference/provisioning/wifi_provisioning', # Fails due to `https://<mdns-hostname>.local`
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
|
|
linkcheck_ignore = ['https://webhome.phy.duke.edu/~rgb/General/dieharder.php', # Certificate error
|
|
|
|
'https://dl.espressif.com/dl/esp32s3_rom.elf', # Not published
|
|
|
|
'https://docs.espressif.com/projects/esptool/en/latest/esp32c2/espefuse/index.html', # Not published
|
|
|
|
'https://www.espressif.com/sites/default/files/documentation/esp32-c2_datasheet_en.pdf', # Not published
|
|
|
|
]
|
|
|
|
|
|
|
|
|
2021-11-12 09:20:03 +00:00
|
|
|
# Custom added feature to allow redirecting old URLs
|
|
|
|
with open('../page_redirects.txt') as f:
|
|
|
|
lines = [re.sub(' +', ' ', line.strip()) for line in f.readlines() if line.strip() != '' and not line.startswith('#')]
|
|
|
|
for line in lines: # check for well-formed entries
|
|
|
|
if len(line.split(' ')) != 2:
|
|
|
|
raise RuntimeError('Invalid line in page_redirects.txt: %s' % line)
|
|
|
|
html_redirect_pages = [tuple(line.split(' ')) for line in lines]
|
2021-11-09 09:11:01 +00:00
|
|
|
|
2021-09-03 02:29:19 +00:00
|
|
|
html_static_path = ['../_static']
|
|
|
|
|
2021-11-09 09:11:01 +00:00
|
|
|
|
|
|
|
# Callback function for user setup that needs be done after `config-init`-event
|
|
|
|
# config.idf_target is not available at the initial config stage
|
|
|
|
def conf_setup(app, config):
|
|
|
|
config.add_warnings_content = 'This document is not updated for {} yet, so some of the content may not be correct.'.format(config.idf_target.upper())
|
|
|
|
|
|
|
|
add_warnings_file = '{}/../docs_not_updated/{}.txt'.format(app.confdir, config.idf_target)
|
|
|
|
try:
|
|
|
|
with open(add_warnings_file) as warning_file:
|
|
|
|
config.add_warnings_pages = warning_file.read().splitlines()
|
|
|
|
except FileNotFoundError:
|
|
|
|
# Not for all target
|
|
|
|
pass
|
|
|
|
|
|
|
|
|
|
|
|
user_setup_callback = conf_setup
|