add rtd

r-cute · Jun 22, 2024 · 9b1d564 · 9b1d564
1 parent 77cebfb
commit 9b1d564
Show file tree

Hide file tree

Showing 61 changed files with 778 additions and 9 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/get_qweather_key.vid.html b/docs/get_qweather_key.vid.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/manual/en/_static/cf_list.dev.png b/docs/manual/en/_static/cf_list.dev.png
diff --git a/docs/manual/en/_static/cf_opt.web.png b/docs/manual/en/_static/cf_opt.web.png
diff --git a/docs/manual/en/_static/clock_faces.web.png b/docs/manual/en/_static/clock_faces.web.png
diff --git a/docs/manual/en/_static/custom.css b/docs/manual/en/_static/custom.css
@@ -0,0 +1,13 @@
+.inline{display: inline}
+.block{display:block}
+
+img.dev{width:160px;}
+figure:has(>img.dev){display: flex;align-items: center;}
+figure>img.dev{margin-right: 1em}
+
+img.web{border:1px solid gray; border-radius: 4px; max-width: 300px}
+
+div:has(>iframe){text-align: center;width:100%;margin: 1.5em auto;}
+iframe{display: block;margin: 0.5em auto;}
+div.hor>iframe{width:100%;aspect-ratio: 16/9;max-width: 550px}
+div.ver>iframe{width:70%;aspect-ratio: 9/16;max-width: 300px}
diff --git a/docs/manual/en/_static/gallery.web.png b/docs/manual/en/_static/gallery.web.png
diff --git a/docs/manual/en/_static/input.png b/docs/manual/en/_static/input.png
diff --git a/docs/manual/en/_static/left_btn_back.dev.png b/docs/manual/en/_static/left_btn_back.dev.png
diff --git a/docs/manual/en/_static/left_btn_func.dev.png b/docs/manual/en/_static/left_btn_func.dev.png
diff --git a/docs/manual/en/_static/menu_cf.dev.png b/docs/manual/en/_static/menu_cf.dev.png
diff --git a/docs/manual/en/_static/menu_settings.dev.png b/docs/manual/en/_static/menu_settings.dev.png
diff --git a/docs/manual/en/_static/ota.web.png b/docs/manual/en/_static/ota.web.png
diff --git a/docs/manual/en/_static/settings.dev.png b/docs/manual/en/_static/settings.dev.png
diff --git a/docs/manual/en/_static/settings.web.png b/docs/manual/en/_static/settings.web.png
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/clock_faces.rst b/docs/manual/en/clock_faces.rst
@@ -0,0 +1,48 @@
+Clock Faces
+=================
+
+
+.. figure:: _static/menu_cf.dev.png
+   :class: dev
+
+   进入设备的表盘界面
+
+.. figure:: _static/cf_list.dev.png
+   :class: dev
+
+   里面包括几个系统自带的表盘和 3 个可选表盘
+
+
+Built-in clock faces
+--------------------------
+
+系统自带的表盘可以在设置页面中简单的颜色或样式的自定义，“默认” 按钮则恢复初始设置，点击 “保存” 后生效。
+
+.. image:: _static/clock_faces.web.png
+   :class: web
+   :align: center
+
+\
+
+
+Optional clock faces
+-------------------------
+
+可选表盘需要通过下载获得
+
+在 “表盘” 栏的下拉菜单选择的 “可选表盘n”，点击 “表盘广场” 链接
+
+.. image:: _static/cf_opt.web.png
+   :class: web
+   :align: center
+
+\
+
+点击相应的主题表盘右侧的 ⬇️ 按钮便可下载
+
+.. image:: _static/gallery.web.png
+   :class: web
+   :align: center
+
+\
+
diff --git a/docs/manual/en/conf.py b/docs/manual/en/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 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_css_files = ['custom.css']
+
+html_theme_options = {
+    'collapse_navigation': False
+}
diff --git a/docs/manual/en/faq.rst b/docs/manual/en/faq.rst
@@ -0,0 +1,61 @@
+FAQ
+============
+
+如何重置 WiFi？
+----------------
+
+设备启动时若无法连接 WiFi，会自动进入 WiFi 配网状态。
+
+在设备已经联网时，如果需要重置或更改 WiFi 配置，可以手动让设备进入配网状态：
+
+	#. 在设备上电前按住 **左键** ，并在启动时保持按下状态约 1 秒直到 “嘀” 的一声。
+	#. 根据提示连接设备提供的 WiFi 热点进行设置。
+
+无法访问设置页面
+---------------------------
+
+	#. 确保设备与您的手机处于同一局域网内。
+	#. `开启设备的设置功能 <settings/>`_
+
+没有天气数据
+-------------------
+
+	#. 完成 `天气设置 <weather/>`_
+	#. 若天气界面仍然没有数据，可点击右键刷新，根据和风天气网站对应的 `错误状态码 <https://dev.qweather.com/docs/resource/status-code/>`_ 排查原因。
+
+下载表盘后设备不断重启
+------------------------------
+
+表盘下载过程出错或表盘文件本身格式错误都可能导致设备在加载表盘时出错而重启。
+
+您可以尝试让设备启动时跳过表盘加载，然后进入设置页面删除可选表盘：
+
+	#. 在设备上电前按住 **右键** ，并在启动时保持按下状态约 1 秒直到 “嘀” 的一声。
+	#. 若设备能顺利启动，您可以在 *设置* 页面 → *表盘* → *(可选表盘n)* → 点击 *删除* 按钮来删除对应表盘。
+	#. 若问题仍未解决，您可以尝试 :ref:`恢复出厂设置 <如何恢复出厂设置？>` 。
+
+
+
+如何恢复出厂设置？
+-------------------------
+
+* 在设置页面点击 **重置** 按钮，设备将恢复出厂设置并重启。
+
+\
+
+* 也可以在设备启动阶段恢复出厂设置：
+
+	#. 在设备上电前同时按住 **左键和右键** ，并在启动时保持按下状态约 1 秒直到 “嘀嘀” 两声。	
+	#. 此时设备将删除设置页面里的所有个性化设置（包括和风天气的 KEY 和可选表盘），但保留 WiFi 设置。
+
+
+
+如何制作表盘？
+------------------
+
+表盘制作教程还在准备中...
+
+能否刷入第三方固件？
+--------------------------
+
+不能，设备串口已关闭。
diff --git a/docs/manual/en/index.rst b/docs/manual/en/index.rst
@@ -0,0 +1,40 @@
+User Manual
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   wifi_provision
+   input
+   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/input.rst b/docs/manual/en/input.rst
@@ -0,0 +1,20 @@
+Dial and Buttons
+==================
+
+.. image:: _static/input.png
+   :align: center
+   :scale: 75%
+\   
+
+| 当左键对应图标 ← 时，点击左键将返回到上一级菜单。
+| 但在少数应用中，左键已被其他功能占用，要返回上一级菜单，需要长按左键约半秒直至其图标变为 ← 。
+
+.. figure:: _static/left_btn_func.dev.png
+   :class: dev
+
+   例如，在番茄钟界面里，左键 ↺ 为重置计时功能
+
+.. figure:: _static/left_btn_back.dev.png
+   :class: dev
+
+   长按左键，图标变成 ←
diff --git a/docs/manual/en/ota.rst b/docs/manual/en/ota.rst
@@ -0,0 +1,10 @@
+OTA Update
+=============
+
+You can check for available firmware updates in the "Update" section.
+
+.. image:: _static/ota.web.png
+   :class: web
+   :align: center
+
+\
diff --git a/docs/manual/en/perfmon.rst b/docs/manual/en/perfmon.rst
@@ -0,0 +1,2 @@
+Perfmon
+===============
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		<html><script>location.pathname='xdial_cf_gallery';</script><body></body></html>