Skip to content

Commit b4052eb

Browse files
vikramdattuvikramdattu
committed
Use esp-docs: Added changes to make use of esp-doc
1 parent 0252956 commit b4052eb

18 files changed

+199
-146
lines changed

‎.gitlab-ci.yml

+67-1
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ variables:
88
MAKEFLAGS: "-j8 --no-keep-going"
99
APP_BUILD: "all"
1010
GIT_SUBMODULE_STRATEGY: recursive
11+
ESP_DOCS_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.0:2-2"
12+
ESP_DOCS_PATH: "$CI_PROJECT_DIR"
1113

1214
before_script:
1315
# add gitlab ssh key
@@ -187,7 +189,71 @@ unit_tests:
187189
paths:
188190
- $CI_PROJECT_DIR/components/esp_diag_data_store/test/python_tests/*html
189191

190-
push_master_to_github:
192+
build_docs:
193+
stage: build
194+
image: $ESP_DOCS_ENV_IMAGE
195+
tags:
196+
- build_docs
197+
artifacts:
198+
paths:
199+
- docs/_build/*/*/*.txt
200+
- docs/_build/*/*/html/*
201+
expire_in: 4 days
202+
# No cleaning when the artifacts
203+
after_script: []
204+
script:
205+
- cd docs
206+
- pip install -r requirements.txt
207+
- build-docs -l en -t esp32
208+
209+
.deploy_docs_template:
210+
stage: deploy
211+
image: $ESP_DOCS_ENV_IMAGE
212+
tags:
213+
- deploy_docs
214+
needs:
215+
- build_docs
216+
only:
217+
changes:
218+
- "docs/**/*"
219+
script:
220+
- source ${CI_PROJECT_DIR}/docs/utils.sh
221+
- add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER
222+
- export GIT_VER=$(git describe --always)
223+
- pip install -r ${CI_PROJECT_DIR}/docs/requirements.txt
224+
- deploy-docs
225+
226+
deploy_docs_preview:
227+
extends:
228+
- .deploy_docs_template
229+
except:
230+
refs:
231+
- main
232+
variables:
233+
TYPE: "preview"
234+
DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/"
235+
DOCS_DEPLOY_PRIVATEKEY: "$DOCS_PREVIEW_PRIVATEKEY"
236+
DOCS_DEPLOY_SERVER: "$DOCS_PREVIEW_SERVER"
237+
DOCS_DEPLOY_SERVER_USER: "$DOCS_PREVIEW_USER"
238+
DOCS_DEPLOY_PATH: "$DOCS_PREVIEW_PATH"
239+
DOCS_DEPLOY_URL_BASE: "$DOCS_PREVIEW_URL_BASE"
240+
241+
deploy_docs_production:
242+
extends:
243+
- .deploy_docs_template
244+
only:
245+
refs:
246+
- main
247+
variables:
248+
TYPE: "production"
249+
DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/"
250+
DOCS_DEPLOY_PRIVATEKEY: "$DOCS_PROD_PRIVATEKEY"
251+
DOCS_DEPLOY_SERVER: "$DOCS_PROD_SERVER"
252+
DOCS_DEPLOY_SERVER_USER: "$DOCS_PROD_USER"
253+
DOCS_DEPLOY_PATH: "$DOCS_PROD_PATH"
254+
DOCS_DEPLOY_URL_BASE: "$DOCS_PROD_URL_BASE"
255+
256+
push_main_to_github:
191257
stage: deploy
192258
image: espressif/idf:release-v5.0
193259
tags:

‎docs/Doxyfile

+15-14
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,15 @@ PROJECT_NAME = "ESP Insights Programming Guide"
2222

2323
INPUT = \
2424
## ESP Insights
25-
../components/esp_insights/include/esp_insights.h \
25+
$(PROJECT_PATH)/components/esp_insights/include/esp_insights.h \
2626
## ESP Diagnostics
27-
../components/esp_diagnostics/include/esp_diagnostics.h \
28-
../components/esp_diagnostics/include/esp_diagnostics_metrics.h \
29-
../components/esp_diagnostics/include/esp_diagnostics_variables.h \
30-
../components/esp_diagnostics/include/esp_diagnostics_system_metrics.h \
31-
../components/esp_diagnostics/include/esp_diagnostics_network_variables.h \
27+
$(PROJECT_PATH)/components/esp_diagnostics/include/esp_diagnostics.h \
28+
$(PROJECT_PATH)/components/esp_diagnostics/include/esp_diagnostics_metrics.h \
29+
$(PROJECT_PATH)/components/esp_diagnostics/include/esp_diagnostics_variables.h \
30+
$(PROJECT_PATH)/components/esp_diagnostics/include/esp_diagnostics_system_metrics.h \
31+
$(PROJECT_PATH)/components/esp_diagnostics/include/esp_diagnostics_network_variables.h \
3232
## RTC Store
33-
../components/rtc_store/include/rtc_store.h
33+
$(PROJECT_PATH)/components/esp_diag_data_store/include/esp_diag_data_store.h
3434

3535
## Get warnings for functions that have no documentation for their parameters or return value
3636
##
@@ -41,11 +41,13 @@ WARN_NO_PARAMDOC = YES
4141
ENABLE_PREPROCESSING = YES
4242
MACRO_EXPANSION = YES
4343
EXPAND_ONLY_PREDEF = YES
44-
PREDEFINED = CONFIG_DIAG_ENABLE_METRICS=1 \
45-
CONFIG_DIAG_ENABLE_VARIABLES=1 \
46-
CONFIG_DIAG_ENABLE_NETWORK_VARIABLES=1 \
47-
CONFIG_DIAG_ENABLE_HEAP_METRICS=1 \
48-
CONFIG_DIAG_ENABLE_WIFI_METRICS=1
44+
PREDEFINED = \
45+
$(ENV_DOXYGEN_DEFINES) \
46+
CONFIG_DIAG_ENABLE_METRICS=1 \
47+
CONFIG_DIAG_ENABLE_VARIABLES=1 \
48+
CONFIG_DIAG_ENABLE_NETWORK_VARIABLES=1 \
49+
CONFIG_DIAG_ENABLE_HEAP_METRICS=1 \
50+
CONFIG_DIAG_ENABLE_WIFI_METRICS=1
4951

5052
## Extract all
5153
EXTRACT_ALL = YES
@@ -62,7 +64,7 @@ XML_OUTPUT = xml
6264
GENERATE_HTML = NO
6365
HAVE_DOT = NO
6466
GENERATE_LATEX = NO
65-
GENERATE_MAN = NO
67+
GENERATE_MAN = YES
6668
GENERATE_RTF = NO
6769

6870
## Skip distracting progress messages
@@ -71,4 +73,3 @@ QUIET = YES
7173
## Log warnings in a file for further review
7274
##
7375
WARN_LOGFILE = "_build/doxygen-warning-log.txt"
74-

‎docs/README.md

+4-5
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,12 @@ This folder contains source files of **ESP Insights API documentation**.
44

55
# Hosted Documentation
66

7-
[TODO]: <> (Fix the link)
8-
* Check here: https://insights.espressif.com/docs/c-apis/en/latest
7+
* Check the following link for the documentation: https://docs.espressif.com/projects/esp-insights
98

109
The above URL is for the main branch latest version.
1110

1211
# Building Documentation
1312

14-
* Install `make` and `doxygen` for your platform (`make` may already be installed as an ESP-IDF prerequisite).
15-
* Change to the docs directory and run `make html`
16-
* `make` will probably prompt you to run a python pip install step to get some other Python-related prerequisites. Run the command as shown, then re-run `make html` to build the docs.
13+
* ESP-Insights uses esp-docs for building the docs.
14+
* Change to the docs directory and run `build-docs -l en -t esp32`
15+
* To understand more about ESP-Docs, please follow https://docs.espressif.com/projects/esp-docs.

‎docs/c-apis/esp_diag_data_store.rst

-6
This file was deleted.

‎docs/c-apis/esp_diag_metrics.rst

-10
This file was deleted.

‎docs/c-apis/esp_diag_variables.rst

-10
This file was deleted.

‎docs/c-apis/index.rst

-11
This file was deleted.

‎docs/conf.py

-83
This file was deleted.

‎docs/conf_common.py

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Common (non-language-specific) configuration for Sphinx
4+
#
5+
6+
# type: ignore
7+
# pylint: disable=wildcard-import
8+
# pylint: disable=undefined-variable
9+
10+
from __future__ import print_function, unicode_literals
11+
12+
from esp_docs.conf_docs import * # noqa: F403,F401
13+
14+
extensions += ['sphinx_copybutton',
15+
# Needed as a trigger for running doxygen
16+
'esp_docs.esp_extensions.dummy_build_system',
17+
'esp_docs.esp_extensions.run_doxygen'
18+
]
19+
20+
# link roles config
21+
github_repo = 'espressif/esp-insights'
22+
23+
# context used by sphinx_idf_theme
24+
html_context['github_user'] = 'espressif'
25+
html_context['github_repo'] = 'esp-insights'
26+
html_static_path = ['../_static']
27+
28+
# Extra options required by sphinx_idf_theme
29+
project_slug = 'esp-insights'
30+
# versions_url = './_static/modbus_docs_versions.js'
31+
32+
idf_targets = ['esp32', 'esp32s3', 'esp32c2', 'esp32c3']
33+
languages = ['en']

‎docs/en/conf.py

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# English Language RTD & Sphinx config file
4+
#
5+
# Uses ../conf_common.py for most non-language-specific settings.
6+
7+
# Importing conf_common adds all the non-language-specific
8+
# parts to this conf module
9+
try:
10+
from conf_common import * # noqa: F403,F401
11+
except ImportError:
12+
import os
13+
import sys
14+
sys.path.insert(0, os.path.abspath('../'))
15+
from conf_common import * # noqa: F403,F401
16+
17+
import datetime
18+
19+
current_year = datetime.datetime.now().year
20+
21+
# General information about the project.
22+
project = u'ESP-Insights Programming Guide'
23+
copyright = u'2021 - {}, Espressif Systems (Shanghai) Co., Ltd'.format(current_year)
24+
25+
# The language for content autogenerated by Sphinx. Refer to documentation
26+
# for a list of supported languages.
27+
language = 'en'

‎docs/en/esp_diag_data_store.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Diagnostics Data Store
2+
######################
3+
4+
DIAG Data Store
5+
---------------
6+
.. include-build-file:: inc/esp_diag_data_store.inc

‎docs/en/esp_diag_metrics.rst

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
ESP Diagnostics Metrics
2+
#######################
3+
4+
Metrics
5+
-------
6+
.. include-build-file:: inc/esp_diagnostics_metrics.inc
7+
8+
System Metrics
9+
--------------
10+
.. include-build-file:: inc/esp_diagnostics_system_metrics.inc

‎docs/en/esp_diag_variables.rst

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
ESP Diagnostics Variables
2+
#########################
3+
4+
Variables
5+
---------
6+
.. include-build-file:: inc/esp_diagnostics_variables.inc
7+
8+
Network Variables
9+
-----------------
10+
.. include-build-file:: inc/esp_diagnostics_network_variables.inc

‎docs/c-apis/esp_diagnostics.rst renamed to ‎docs/en/esp_diagnostics.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@ ESP Diagnostics
33

44
Diagnostics
55
-----------
6-
.. include:: /_build/inc/esp_diagnostics.inc
6+
.. include-build-file:: inc/esp_diagnostics.inc

‎docs/c-apis/esp_insights.rst renamed to ‎docs/en/esp_insights.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@ ESP Insights
33

44
Insights
55
--------
6-
.. include:: /_build/inc/esp_insights.inc
6+
.. include-build-file:: inc/esp_insights.inc

‎docs/index.rst renamed to ‎docs/en/index.rst

+6-2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ ESP Insights is a remote diagnostics solution that allows users to remotely moni
55
This is the C API (for firmware) documentation for ESP Insights.
66

77
.. toctree::
8-
:maxdepth: 2
8+
:maxdepth: 4
99

10-
C APIs <c-apis/index>
10+
esp_insights.rst
11+
esp_diagnostics.rst
12+
esp_diag_metrics.rst
13+
esp_diag_variables.rst
14+
esp_diag_data_store.rst

0 commit comments

Comments
 (0)