add rtd

r-cute · Jun 21, 2024 · afd7f16 · afd7f16
1 parent 77cebfb
commit afd7f16
Show file tree

Hide file tree

Showing 43 changed files with 469 additions and 8 deletions.
diff --git a/.github/workflows/build-gh-pages-action.yml b/.github/workflows/build-gh-pages-action.yml
@@ -0,0 +1,61 @@
+name: Build and deploy website to github pages
+
+# execute this workflow automatically when a we push to master
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+
+  build_docs_job:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: Checkout
+        uses: actions/[email protected]
+
+      - name: Set up Python
+        uses: actions/[email protected]
+        with:
+          python-version: 3.9
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U sphinx
+          python -m pip install -r docs/manual/requirements.txt
+
+      - name: make the sphinx docs
+        run: |
+          cd docs/manual
+          bash gh_make.sh ../../manual
+          cd ../..
+          cp docs/manual/index.html manual
+          rm -r docs/manual
+          mv manual docs
+
+      # - name: Init new repo in dist folder and commit generated files
+      #   run: |
+      #     cd _build_docs
+      #     git init
+      #     git add -A
+      #     git config --local user.email "[email protected]"
+      #     git config --local user.name "GitHub Action"
+      #     git commit -m 'deploy'
+
+      - uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          force_orphan: true
+
+      # - name: Force push to destination branch
+      #   uses: ad-m/[email protected]
+      #   with:
+      #     github_token: ${{ secrets.GITHUB_TOKEN }}
+      #     branch: gh-pages
+      #     force: true
+      #     directory: ./_build_docs
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+*_build/
diff --git a/README.md b/README.md
@@ -1 +1,5 @@
-# XDial web pages
+# XDial web pages
+
+zh-cn [![Documentation Status](https://readthedocs.org/projects/xdial/badge/?version=latest)](https://xdial.readthedocs.io/zh-cn/latest/?badge=latest)
+
+en [![Documentation Status](https://readthedocs.org/projects/xdial-en/badge/?version=latest)](https://xdial.readthedocs.io/en/latest/?badge=latest)
diff --git a/docs/faq.html b/docs/faq.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html><html><head><title>XDial</title><meta charset="UTF-8"><meta name='viewport' content='width=device-width, initial-scale=1'/><style>
+<!DOCTYPE html><html><head><title>xDial</title><meta charset="UTF-8"><meta name='viewport' content='width=device-width, initial-scale=1'/><style>
 	*{font-size:1em;margin:.25em}h1{font-size:1.25em;text-align:center;}
 	h2{margin:.75em auto;}h2::after{content:"➖";float:right;}.hidden>h2::after{content:"➕"}
 	.hidden>:not(h2){display:none}section{border-top:1px solid #ccc}
@@ -39,7 +39,7 @@ <h2>没有天气数据</h2>
 				<li><a href='https://dev.qweather.com/' target='_blank'>注册</a>和风天气的开发账号。</li>
 				<li>登录<a href='https://console.qweather.com/#/apps' target='_blank'>项目管理</a>页面 > 点击<i>创建项目</i> > 选择<i>免费订阅</i>和<i>Web API</i> > <i>创建</i> > <i>查看</i>并复制 KEY。</li>
 				<li>转到<i>设置</i>页面，在<i>天气</i>里填入 KEY，查找并选择您所在城市，然后点击<i>保存</i>。</li>
-				<li>进入设备的<u>天气</u>界面查看，若仍然没有数据，可点击右键刷新，根据对应的<a href='https://dev.qweather.com/docs/resource/status-code/' target='_blank'>错误状态码</a>排查原因。</li>
+				<li>进入设备的<u>天气</u>界面查看，若仍然没有数据，可点击右键刷新，根据对应的<a href='https://dev.qweather.com/docs/resource/status-code/' target='_blank'>错误状态码</a>可选表盘</li>
 			</ol>
 		</p>
 		<p><a href='get_qweather_key.vid.html' target='_blank'>视频演示</a></p>
@@ -48,12 +48,12 @@ <h2>没有天气数据</h2>
 		</p>
 	</section>	
 	<section id='delete_clock_face'>
-		<h2>下载自选表盘后设备不断重启</h2>
+		<h2>下载可选表盘后设备不断重启</h2>
 		<p>表盘下载过程出错或表盘文件本身格式错误都可能导致设备在加载表盘时出错而重启。</p>
-		<p>您可以尝试让设备启动时跳过表盘加载，然后进入设置页面删除自选表盘：
+		<p>您可以尝试让设备启动时跳过表盘加载，然后进入设置页面删除可选表盘：
 			<ol>
 				<li>在设备上电前按住<em>右</em>键，并在启动时保持按下状态约1秒直到“嘀”的一声。</li>
-				<li>若设备能顺利启动，您可以在<i>设置</i>页面 > <i>表盘</i> > <i>(自选表盘)</i> > 点击<i>删除</i>按钮来删除自选表盘。</li>
+				<li>若设备能顺利启动，您可以在<i>设置</i>页面 > <i>表盘</i> > <i>(可选表盘)</i> > 点击<i>删除</i>按钮来删除可选表盘。</li>
 				<li>若问题仍未解决，您可以尝试<a href='#' onclick='q("#factory_reset>h2").click()'>恢复出厂设置</a>。</li>
 			</ol>
 		</p>
@@ -63,7 +63,7 @@ <h2>如何恢复出厂设置？</h2>
 		<p>您可以在设备启动阶段恢复出厂设置，这可能有助于解决一些未知问题：
 			<ol>
 				<li>在设备上电前同时按住<em>左</em>键和<em>右</em>键，并在启动时保持按下状态约1秒直到“嘀嘀”两声。</li>
-				<li>此时设备将删除设置页面里的所有个性化设置（包括和风天气的 KEY 和自选表盘），但保留 WiFi 设置。</li>
+				<li>此时设备将删除设置页面里的所有个性化设置（包括和风天气的 KEY 和可选表盘），但保留 WiFi 设置。</li>
 			</ol>
 		</p>
 	</section>

diff --git a/docs/gallery/index.html b/docs/gallery/index.html
@@ -0,0 +1 @@
+<html><script>location.pathname='xdial_cf_gallery';</script><body></body></html>
diff --git a/docs/index.html b/docs/index.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html><html><head><title>XDial</title><meta charset="UTF-8"><meta name='viewport' content='width=device-width, initial-scale=1'/><style>
+<!DOCTYPE html><html><head><title>xDial</title><meta charset="UTF-8"><meta name='viewport' content='width=device-width, initial-scale=1'/><style>
 
 </style><script src='util.js'></script><script>
 

diff --git a/docs/manual/en/.readthedocs.yaml b/docs/manual/en/.readthedocs.yaml
@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/manual/en/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/manual/requirements.txt
diff --git a/docs/get_qweather_key.vid.html → ...nual/en/_static/get_qweather_key.vid.html b/docs/get_qweather_key.vid.html → ...nual/en/_static/get_qweather_key.vid.html
diff --git a/docs/manual/en/_static/wifi_prov.dev.png b/docs/manual/en/_static/wifi_prov.dev.png
diff --git a/docs/manual/en/_static/wifi_prov.vid.html b/docs/manual/en/_static/wifi_prov.vid.html
@@ -0,0 +1 @@
+<html><script>location.href="http://www.bilibili.com/blackboard/html5mobileplayer.html?aid=1252461039&bvid=BV1sJ4m1j7SP&cid=1486040529&p=1&high_quality=1&danmaku=0&autoplay=1"</script><body></body></html>
diff --git a/docs/manual/en/clock_faces.rst b/docs/manual/en/clock_faces.rst
@@ -0,0 +1,2 @@
+Clock faces
+================
diff --git a/docs/manual/en/conf.py b/docs/manual/en/conf.py
@@ -0,0 +1,32 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'xDial user manual'
+copyright = '2024, hyan'
+author = 'hyan'
+release = '1.0.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinx.ext.githubpages', 'sphinx.ext.autosectionlabel']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+language = 'en'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+html_theme_options = {
+    'collapse_navigation': False
+}
diff --git a/docs/manual/en/faq.rst b/docs/manual/en/faq.rst
@@ -0,0 +1,2 @@
+FAQ
+============
diff --git a/docs/manual/en/index.rst b/docs/manual/en/index.rst
@@ -0,0 +1,39 @@
+User manual
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   wifi_provision
+   settings
+   ota
+   clock_faces
+   weather
+   perfmon
+   faq
+
+
+Product parameters
+--------------------
+
+.. csv-table::
+
+   "Shell", "Resin 3D printed"
+   "Size", "52*47*54 mm"
+   "Screen", "Ø 32 mm, 240*240 pixels"
+   "Power", "DC 5V, USB Type-C (no battery)"
+   "Processor", "ESP32-C3"
+   "WiFi", "2.4 GHz, 802.11 b/g/n"
+   "Flash", "32 Mbit"
+   "Language", "En/中文"
+
+⚠️ The shell is 3D printed with resin, it may soften and deform in high-temperature environment.
+
+
+..
+      Indices and tables
+      ==================
+
+      * :ref:`genindex`
+      * :ref:`modindex`
+      * :ref:`search`
diff --git a/docs/manual/en/ota.rst b/docs/manual/en/ota.rst
@@ -0,0 +1,2 @@
+OTA update
+==================
diff --git a/docs/manual/en/perfmon.rst b/docs/manual/en/perfmon.rst
@@ -0,0 +1,2 @@
+Perfmon
+===============
diff --git a/docs/manual/en/settings.rst b/docs/manual/en/settings.rst
@@ -0,0 +1,2 @@
+Settings
+=============
diff --git a/docs/manual/en/weather.rst b/docs/manual/en/weather.rst
@@ -0,0 +1,2 @@
+Weather
+===========
diff --git a/docs/manual/en/wifi_provision.rst b/docs/manual/en/wifi_provision.rst
@@ -0,0 +1,2 @@
+WiFi provision
+===================
diff --git a/docs/manual/gh_make.sh b/docs/manual/gh_make.sh
@@ -0,0 +1,6 @@
+declare -a lang_ls=("en" "zh-cn")
+
+for lang in "${lang_ls[@]}"
+do
+	sphinx-build -b html -d ${lang}/_build/doctrees ${lang} ${1}/${lang}
+done
diff --git a/docs/manual/index.html b/docs/manual/index.html
@@ -0,0 +1 @@
+<html><script>location.pathname='xdial/manual/zh-cn/';</script><body></body></html>
diff --git a/docs/manual/make.bat b/docs/manual/make.bat
@@ -0,0 +1,5 @@
+@echo off 
+set list=en zh-cn 
+(for %%a in (%list%) do ( 
+   sphinx-build -M html %%a %%a/_build
+))
diff --git a/docs/manual/requirements.txt b/docs/manual/requirements.txt
@@ -0,0 +1 @@
+sphinx-rtd-theme
diff --git a/docs/manual/zh-cn/.readthedocs.yaml b/docs/manual/zh-cn/.readthedocs.yaml
@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/manual/zh-cn/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/manual/requirements.txt
diff --git a/docs/manual/zh-cn/_static/back.dev.png b/docs/manual/zh-cn/_static/back.dev.png
diff --git a/docs/manual/zh-cn/_static/custom.css b/docs/manual/zh-cn/_static/custom.css
@@ -0,0 +1,8 @@
+img.dev{width:160px}
+.inline{display: inline}
+.block{display:block}
+p,div.line{text-indent: 2em}
+figure{display: flex;align-items: center;}
+figure>img{margin-right: 1em}
+
+iframe{margin:1em auto;display:block;}
diff --git a/docs/manual/zh-cn/_static/get_qweather_key.vid.html b/docs/manual/zh-cn/_static/get_qweather_key.vid.html
@@ -0,0 +1 @@
+<html><script>location.href="http://www.bilibili.com/blackboard/html5mobileplayer.html?aid=1252461039&bvid=BV1sJ4m1j7SP&cid=1486040529&p=1&high_quality=1&danmaku=0&autoplay=1"</script><body></body></html>
diff --git a/docs/manual/zh-cn/_static/left_btn_back.dev.png b/docs/manual/zh-cn/_static/left_btn_back.dev.png
diff --git a/docs/manual/zh-cn/_static/left_btn_func.dev.png b/docs/manual/zh-cn/_static/left_btn_func.dev.png
diff --git a/docs/manual/zh-cn/_static/menu_settings.dev.png b/docs/manual/zh-cn/_static/menu_settings.dev.png
diff --git a/docs/manual/zh-cn/_static/settings.dev.png b/docs/manual/zh-cn/_static/settings.dev.png
diff --git a/docs/manual/zh-cn/_static/wifi_prov.dev.png b/docs/manual/zh-cn/_static/wifi_prov.dev.png
diff --git a/docs/manual/zh-cn/_static/wifi_prov.vid.html b/docs/manual/zh-cn/_static/wifi_prov.vid.html
@@ -0,0 +1 @@
+<html><script>location.href="http://www.bilibili.com/blackboard/html5mobileplayer.html?aid=1252461039&bvid=BV1sJ4m1j7SP&cid=1486040529&p=1&high_quality=1&danmaku=0&autoplay=1"</script><body></body></html>
diff --git a/docs/manual/zh-cn/clock_faces.rst b/docs/manual/zh-cn/clock_faces.rst
@@ -0,0 +1,10 @@
+表盘
+=======
+
+设备的表盘选择界面里有一些系统自带的表盘，可以在设置页面中对其样式、颜色进行简单的自定义。 
+
+另外还有几个可选表盘，它们可以通过下载替换：
+
+	#. 从下拉菜单选择对应的可选表盘n
+	#. 进入 表盘广场 页面
+	#. 点击 ⬇️ 按钮便可下载对应的主题表盘
diff --git a/docs/manual/zh-cn/conf.py b/docs/manual/zh-cn/conf.py
@@ -0,0 +1,34 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'xDial 使用说明'
+copyright = '2024, hyan'
+author = 'hyan'
+release = '1.0.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinx.ext.githubpages', 'sphinx.ext.autosectionlabel']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+language = 'zh_cn'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+html_css_files = ['custom.css']
+
+html_theme_options = {
+    'collapse_navigation': False
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		<html><script>location.pathname='xdial_cf_gallery';</script><body></body></html>
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		<html><script>location.href="http://www.bilibili.com/blackboard/html5mobileplayer.html?aid=1252461039&bvid=BV1sJ4m1j7SP&cid=1486040529&p=1&high_quality=1&danmaku=0&autoplay=1"</script><body></body></html>
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		<html><script>location.pathname='xdial/manual/zh-cn/';</script><body></body></html>