diff --git a/examples/basic/README.md b/examples/basic/README.md new file mode 100644 index 0000000..8f8e5ba --- /dev/null +++ b/examples/basic/README.md @@ -0,0 +1,3 @@ +# Basic Example + +Basic documentation building example that builds English and Chinese documentation for ESP32. \ No newline at end of file diff --git a/examples/basic/build_example.sh b/examples/basic/build_example.sh new file mode 100755 index 0000000..2b95ee5 --- /dev/null +++ b/examples/basic/build_example.sh @@ -0,0 +1 @@ +build-docs -t esp32 \ No newline at end of file diff --git a/examples/basic/conf_common.py b/examples/basic/conf_common.py new file mode 100644 index 0000000..e4a95e6 --- /dev/null +++ b/examples/basic/conf_common.py @@ -0,0 +1,15 @@ +from esp_docs.conf_docs import * # noqa: F403,F401 + +languages = ['en', 'zh_CN'] +idf_targets = ['esp32'] + +# link roles config +github_repo = 'espressif/esp-idf' + +# 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-idf' +versions_url = 'https://dl.espressif.com/dl/esp-idf/idf_versions.js' diff --git a/examples/basic/en/conf.py b/examples/basic/en/conf.py new file mode 100644 index 0000000..bad05e8 --- /dev/null +++ b/examples/basic/en/conf.py @@ -0,0 +1,24 @@ +# -*- 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' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +language = 'en' diff --git a/examples/basic/en/index.rst b/examples/basic/en/index.rst new file mode 100644 index 0000000..dfb8662 --- /dev/null +++ b/examples/basic/en/index.rst @@ -0,0 +1,5 @@ +ESP-Docs Simple Example +========================= +:link_to_translation:`zh_CN:[中文]` + +This is a simple example for the esp-docs building system. \ No newline at end of file diff --git a/examples/basic/zh_CN/conf.py b/examples/basic/zh_CN/conf.py new file mode 100644 index 0000000..dd5cf1a --- /dev/null +++ b/examples/basic/zh_CN/conf.py @@ -0,0 +1,23 @@ +# -*- 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 乐鑫信息科技（上海）股份有限公司' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +language = 'zh_CN' diff --git a/examples/basic/zh_CN/index.rst b/examples/basic/zh_CN/index.rst new file mode 100644 index 0000000..b1d1406 --- /dev/null +++ b/examples/basic/zh_CN/index.rst @@ -0,0 +1,5 @@ +ESP-Docs Simple Example +========================= +:link_to_translation:`en:[English]` + +This is a simple example for the esp-docs building system. It builds documentation for ESP32 only, English and Chinese version. \ No newline at end of file diff --git a/examples/doxygen/Doxyfile b/examples/doxygen/Doxyfile new file mode 100644 index 0000000..9766a8c --- /dev/null +++ b/examples/doxygen/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/examples/doxygen/README.md b/examples/doxygen/README.md new file mode 100644 index 0000000..aca52a8 --- /dev/null +++ b/examples/doxygen/README.md @@ -0,0 +1,3 @@ +# Doxygen Example + +Simple documentation building example that builds English and Chinese documentation for all targets together with an API-reference generated by doxygen. \ No newline at end of file diff --git a/examples/doxygen/build_example.sh b/examples/doxygen/build_example.sh new file mode 100755 index 0000000..9cfb006 --- /dev/null +++ b/examples/doxygen/build_example.sh @@ -0,0 +1 @@ +build-docs --project-path src/ \ No newline at end of file diff --git a/examples/doxygen/conf_common.py b/examples/doxygen/conf_common.py new file mode 100644 index 0000000..9d204ea --- /dev/null +++ b/examples/doxygen/conf_common.py @@ -0,0 +1,21 @@ +from esp_docs.conf_docs import * # noqa: F403,F401 + +extensions += ['sphinx_copybutton', + # Needed as a trigger for running doxygen + 'esp_docs.esp_extensions.dummy_build_system', + 'esp_docs.esp_extensions.run_doxygen', + ] + +# link roles config +github_repo = 'espressif/esp-idf' + +# 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-idf' +versions_url = 'https://dl.espressif.com/dl/esp-idf/idf_versions.js' + +idf_targets = ['esp32', 'esp32s2', 'esp32c3'] +languages = ['en', 'zh_CN'] diff --git a/examples/doxygen/en/conf.py b/examples/doxygen/en/conf.py new file mode 100644 index 0000000..bad05e8 --- /dev/null +++ b/examples/doxygen/en/conf.py @@ -0,0 +1,24 @@ +# -*- 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' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +language = 'en' diff --git a/examples/doxygen/en/index.rst b/examples/doxygen/en/index.rst new file mode 100644 index 0000000..452d8fd --- /dev/null +++ b/examples/doxygen/en/index.rst @@ -0,0 +1,12 @@ +ESP-Docs Simple Example +========================= +:link_to_translation:`zh_CN:[中文]` + +This is a simple example for the esp-docs building system. + +.. ---------------------------- API Reference ---------------------------------- + +API Reference +------------- + +.. include-build-file:: inc/my_api.inc \ No newline at end of file diff --git a/examples/doxygen/src/README.md b/examples/doxygen/src/README.md new file mode 100644 index 0000000..d73efdb --- /dev/null +++ b/examples/doxygen/src/README.md @@ -0,0 +1 @@ +# Dummy project for showing doxygen intergration \ No newline at end of file diff --git a/examples/doxygen/src/api/my_api.h b/examples/doxygen/src/api/my_api.h new file mode 100644 index 0000000..fb22e99 --- /dev/null +++ b/examples/doxygen/src/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/examples/doxygen/zh_CN/conf.py b/examples/doxygen/zh_CN/conf.py new file mode 100644 index 0000000..dd5cf1a --- /dev/null +++ b/examples/doxygen/zh_CN/conf.py @@ -0,0 +1,23 @@ +# -*- 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 乐鑫信息科技（上海）股份有限公司' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +language = 'zh_CN' diff --git a/examples/doxygen/zh_CN/index.rst b/examples/doxygen/zh_CN/index.rst new file mode 100644 index 0000000..2aff408 --- /dev/null +++ b/examples/doxygen/zh_CN/index.rst @@ -0,0 +1,5 @@ +ESP-Docs Simple Example +========================= +:link_to_translation:`en:[English]` + +This is a simple example for the esp-docs building system. \ No newline at end of file