add rtd

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

Hide file tree

Showing 48 changed files with 549 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/cf_list.dev.png b/docs/manual/zh-cn/_static/cf_list.dev.png
diff --git a/docs/manual/zh-cn/_static/cf_opt.web.png b/docs/manual/zh-cn/_static/cf_opt.web.png
diff --git a/docs/manual/zh-cn/_static/clock_faces.web.png b/docs/manual/zh-cn/_static/clock_faces.web.png
diff --git a/docs/manual/zh-cn/_static/custom.css b/docs/manual/zh-cn/_static/custom.css
@@ -0,0 +1,14 @@
+.inline{display: inline}
+.block{display:block}
+section>p,div.line{text-indent: 2em}
+
+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/zh-cn/_static/gallery.web.png b/docs/manual/zh-cn/_static/gallery.web.png
diff --git a/docs/manual/zh-cn/_static/input.png b/docs/manual/zh-cn/_static/input.png
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_cf.dev.png b/docs/manual/zh-cn/_static/menu_cf.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/ota.web.png b/docs/manual/zh-cn/_static/ota.web.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/settings.web.png b/docs/manual/zh-cn/_static/settings.web.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/clock_faces.rst b/docs/manual/zh-cn/clock_faces.rst
@@ -0,0 +1,48 @@
+表盘
+=======
+
+
+.. figure:: _static/menu_cf.dev.png
+   :class: dev
+
+   进入设备的表盘界面
+
+.. figure:: _static/cf_list.dev.png
+   :class: dev
+
+   里面包括几个系统自带的表盘和 3 个可选表盘
+
+
+系统表盘
+----------
+
+系统自带的表盘可以在设置页面中简单的颜色或样式的自定义，“默认” 按钮则恢复初始设置，点击 “保存” 后生效。
+
+.. image:: _static/clock_faces.web.png
+   :class: web
+   :align: center
+
+\
+
+
+可选表盘
+----------
+
+可选表盘需要通过下载获得
+
+在 “表盘” 栏的下拉菜单选择的 “可选表盘n”，点击 “表盘广场” 链接
+
+.. image:: _static/cf_opt.web.png
+   :class: web
+   :align: center
+
+\
+
+点击相应的主题表盘右侧的 ⬇️ 按钮便可下载
+
+.. image:: _static/gallery.web.png
+   :class: web
+   :align: center
+
+\
+
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>