Add examples for esp-docs

Add two simple examples, for more complex examples see use in esp-idf or other repos

examples/basic/README.md

@@ -0,0 +1,3 @@
+# Basic Example
+
+Basic documentation building example that builds English and Chinese documentation for ESP32.

examples/basic/build_example.sh

@@ -0,0 +1 @@
+build-docs -t esp32

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'

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'

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.

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'

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.

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

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.

examples/doxygen/build_example.sh

@@ -0,0 +1 @@
+build-docs --project-path src/

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']

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'

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

examples/doxygen/src/README.md

@@ -0,0 +1 @@
+# Dummy project for showing doxygen intergration

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);

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'

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.