zcnote-sphinx-theme 0.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,32 @@
1
+ import os
2
+ from pathlib import Path
3
+
4
+ __version__ = "0.0.1"
5
+
6
+ def get_html_theme_path():
7
+ """返回主题文件夹的绝对路径"""
8
+ return os.path.abspath(os.path.join(os.path.dirname(__file__), "theme"))
9
+
10
+ def setup(app):
11
+ """Sphinx 扩展注册入口"""
12
+ # 1. 获取基础路径与当前主题的真实路径
13
+ base_theme_path = get_html_theme_path()
14
+ actual_theme_path = os.path.join(base_theme_path, "zcnote_sphinx_theme")
15
+
16
+ # 2. 注册 HTML 主题
17
+ app.add_html_theme("zcnote_sphinx_theme", actual_theme_path)
18
+
19
+ # =========================================================
20
+ # 将 components 文件夹注入 Sphinx 的模板搜索路径
21
+ # =========================================================
22
+ components_path = os.path.join(actual_theme_path, "components")
23
+ app.config.templates_path.append(components_path)
24
+
25
+ # 3. 自动加载自定义样式,无需用户在 conf.py 中手动配置 html_css_files
26
+ app.add_css_file("css/zcnote_custom.css")
27
+
28
+ return {
29
+ "version": __version__,
30
+ "parallel_read_safe": True,
31
+ "parallel_write_safe": True,
32
+ }
@@ -0,0 +1,7 @@
1
+ {# Displays the version of pydata-sphinx-theme used to build the documentation. #}
2
+ <p class="theme-version">
3
+ <!-- # L10n: Setting the PST URL as an argument as this does not need to be localized -->
4
+ {% trans trimmed theme_version=theme_version|e, PST_url="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html" %}
5
+ Modify and build upon <a href="{{ PST_url }}">PyData Sphinx Theme</a> {{ theme_version }}.
6
+ {% endtrans %}
7
+ </p>
@@ -0,0 +1,122 @@
1
+ {% extends "pydata_sphinx_theme/layout.html" %}
2
+
3
+ {# ==========================================================
4
+ 模块 1:动态控制侧边栏折叠按钮与 Section 标题的互斥显示
5
+ ========================================================== #}
6
+ {% block extrahead %}
7
+ {{ super() }}
8
+
9
+ {% if theme_enable_collapse_sidebar | string | lower == 'false' %}
10
+ <style>
11
+ /* 状态 B:关闭折叠功能 -> 隐藏按钮,保留原标题 */
12
+ .sidebar-primary-item.pst-sidebar-collapse,
13
+ #pst-collapse-sidebar-button {
14
+ display: none !important;
15
+ visibility: hidden !important;
16
+ height: 0 !important;
17
+ padding: 0 !important;
18
+ margin: 0 !important;
19
+ pointer-events: none !important;
20
+ }
21
+ #pst-primary-sidebar .bd-links__title {
22
+ display: block !important;
23
+ }
24
+ </style>
25
+ {% else %}
26
+ <style>
27
+ /* 状态 A:开启折叠功能 -> 隐藏原标题,按钮保留 */
28
+ #pst-primary-sidebar .bd-links__title {
29
+ display: none !important;
30
+ }
31
+ </style>
32
+ {% endif %}
33
+ {% endblock extrahead %}
34
+
35
+ {# ==========================================================
36
+ 模块 2:绝对覆盖 Footer 与零跳动滚动引擎
37
+ ========================================================== #}
38
+ {% block footer %}
39
+ {{ super() }}
40
+
41
+ <script>
42
+ document.addEventListener("DOMContentLoaded", function() {
43
+
44
+ // ---------------------------------------------------------
45
+ // 【新增】:极轻量级 DOM 文本替换(无损修改官方 Collapse 按钮)
46
+ // ---------------------------------------------------------
47
+ {% if theme_enable_collapse_sidebar | string | lower != 'false' %}
48
+ const collapseBtn = document.getElementById("pst-collapse-sidebar-button");
49
+ if (collapseBtn) {
50
+ const newText = "Section Navigation";
51
+
52
+ // 1. 替换按钮内部的文字节点
53
+ const collapseLabel = collapseBtn.querySelector(".pst-collapse-sidebar-label");
54
+ const expandLabel = collapseBtn.querySelector(".pst-expand-sidebar-label");
55
+ if (collapseLabel) collapseLabel.textContent = newText;
56
+ if (expandLabel) expandLabel.textContent = newText;
57
+
58
+ // 2. 暴力覆写 Bootstrap Tooltip (悬浮提示框) 的所有关联属性
59
+ collapseBtn.setAttribute("title", newText);
60
+ collapseBtn.setAttribute("data-bs-original-title", newText);
61
+ collapseBtn.setAttribute("aria-label", newText);
62
+ }
63
+ {% endif %}
64
+
65
+ const footer = document.querySelector(".bd-footer");
66
+
67
+ // 【核心优化】DOM 级联兜底:确保在搜索页、404 等非常规页面依然能找到挂载点
68
+ const targetContainer = document.querySelector(".bd-article-container") ||
69
+ document.querySelector(".bd-content") ||
70
+ document.querySelector(".bd-main") ||
71
+ document.body;
72
+
73
+ if (!footer) return;
74
+
75
+ // 降维转移:将 Footer 提升到 body 级,脱离 Grid 束缚
76
+ document.body.appendChild(footer);
77
+
78
+ // 注入幽灵占位符:稳定主容器高度,打通侧边栏滑动轨道
79
+ const spacer = document.createElement("div");
80
+ spacer.style.width = "100%";
81
+ spacer.style.display = "block";
82
+ spacer.style.clear = "both";
83
+ targetContainer.appendChild(spacer);
84
+
85
+ let ticking = false;
86
+
87
+ // 渲染同步引擎
88
+ function updateLayout() {
89
+ // Read Phase (批量读 DOM,防止布局抖动)
90
+ const footerHeight = footer.offsetHeight;
91
+ const footerTop = footer.getBoundingClientRect().top;
92
+ const viewportHeight = window.innerHeight;
93
+
94
+ let overlap = viewportHeight - footerTop;
95
+ overlap = overlap > 0 ? Math.ceil(overlap) : 0;
96
+
97
+ // Write Phase (批量写 DOM,利用 GPU 加速)
98
+ if (spacer.style.height !== `${footerHeight}px`) {
99
+ spacer.style.height = `${footerHeight}px`;
100
+ }
101
+ document.documentElement.style.setProperty('--zcnote-footer-overlap', `${overlap}px`);
102
+
103
+ ticking = false;
104
+ }
105
+
106
+ function requestTick() {
107
+ if (!ticking) {
108
+ window.requestAnimationFrame(updateLayout);
109
+ ticking = true;
110
+ }
111
+ }
112
+
113
+ // 绑定无源侦听器 (Passive Listeners) 提升滚动流畅度
114
+ window.addEventListener("scroll", requestTick, { passive: true });
115
+ window.addEventListener("resize", requestTick, { passive: true });
116
+
117
+ // 监控 Footer 自身响应式高度的变化
118
+ const ro = new ResizeObserver(() => requestTick());
119
+ ro.observe(footer);
120
+ });
121
+ </script>
122
+ {% endblock %}
@@ -0,0 +1,184 @@
1
+ /* =========================================================
2
+ 1. 防抖:消除长短页面切换时的“滚动条布局偏移”
3
+ ========================================================= */
4
+ html {
5
+ /* 现代标准:始终为滚动条预留出物理空间 */
6
+ scrollbar-gutter: stable;
7
+ /* 兜底防御:针对不支持 scrollbar-gutter 的老旧浏览器 */
8
+ overflow-y: scroll;
9
+ }
10
+
11
+ /* =========================================================
12
+ 2. 全局变量与基础重置
13
+ ========================================================= */
14
+ :root {
15
+ /* JS 动态注入的 Footer 重叠高度计算值(勿动) */
16
+ --zcnote-footer-overlap: 0px;
17
+
18
+ /* 左侧边栏宽度控制阀(自由调节,推荐 12rem ~ 15rem,原版为22rem左右) */
19
+ --zcnote-sidebar-width: 20rem;
20
+ }
21
+
22
+ /* 文本两端对齐与长词换行保护,提升技术文档阅读体验 */
23
+ .bd-article p, .bd-article li {
24
+ text-align: justify;
25
+ text-justify: inter-word;
26
+ overflow-wrap: break-word;
27
+ word-wrap: break-word;
28
+ }
29
+
30
+ /* 页面基准设定,打破外层包裹限制,为 Footer 绝对定位做准备 */
31
+ body {
32
+ position: relative !important;
33
+ min-height: 100vh;
34
+ overflow-x: clip;
35
+ }
36
+
37
+ .bd-page-width {
38
+ position: static !important;
39
+ }
40
+
41
+ /* =========================================================
42
+ 3. Footer 绝对覆盖图层
43
+ ========================================================= */
44
+ .bd-footer {
45
+ position: absolute !important;
46
+ bottom: 0 !important;
47
+ left: 0 !important;
48
+ width: 100% !important;
49
+ margin: 0 !important;
50
+ z-index: 100 !important;
51
+ background-color: var(--pst-color-background) !important;
52
+ border-top: 1px solid var(--pst-color-border) !important;
53
+ }
54
+
55
+ /* =========================================================
56
+ 4. 大屏布局控制:侧边栏、Header对齐与零跳动滚动
57
+ ========================================================= */
58
+ @media (min-width: 1200px) {
59
+
60
+ /* --- 4.1 Header 顶部栏与左侧边栏像素级对齐 --- */
61
+ .bd-header .navbar-header-items__start {
62
+ width: var(--zcnote-sidebar-width) !important;
63
+ flex: 0 0 var(--zcnote-sidebar-width) !important;
64
+ max-width: var(--zcnote-sidebar-width) !important;
65
+ }
66
+
67
+ .bd-header .navbar-header-items {
68
+ flex: 1 1 auto !important;
69
+ width: auto !important;
70
+ max-width: 100% !important;
71
+ }
72
+
73
+ .bd-header .navbar-header-items__start .navbar-brand {
74
+ padding-left: 0.5rem !important;
75
+ }
76
+
77
+ /* --- 4.2 左侧边栏尺寸接管与折叠兼容 --- */
78
+ .bd-sidebar-primary {
79
+ width: var(--zcnote-sidebar-width);
80
+ max-width: var(--zcnote-sidebar-width);
81
+ flex: 0 0 auto; /* 放弃 Flex 霸权,听从 width 指挥 */
82
+
83
+ /* 为 JS 触发的折叠动作注入 Material Design 标准丝滑缓冲动画 */
84
+ transition: width 0.25s cubic-bezier(0.4, 0, 0.2, 1),
85
+ max-width 0.25s cubic-bezier(0.4, 0, 0.2, 1) !important;
86
+ }
87
+
88
+ /* 微调左侧边栏内部留白,向正文归还更多阅读空间 */
89
+ #pst-primary-sidebar .sidebar-primary-item {
90
+ padding-left: 0.5rem !important;
91
+ padding-right: 0.5rem !important;
92
+ }
93
+
94
+ #pst-primary-sidebar .bd-toc-item {
95
+ padding-right: 0.5rem !important;
96
+ }
97
+
98
+ /* --- 4.3 双侧边栏动态防跳动滚动计算 --- */
99
+ #pst-primary-sidebar,
100
+ #pst-secondary-sidebar {
101
+ align-self: start !important;
102
+ position: sticky !important;
103
+ top: var(--pst-header-height) !important;
104
+
105
+ /* 使用 dvh 兼容移动端浏览器地址栏的伸缩,并减去 Footer 遮挡 */
106
+ height: calc(100dvh - var(--pst-header-height) - var(--zcnote-footer-overlap)) !important;
107
+ max-height: calc(100dvh - var(--pst-header-height) - var(--zcnote-footer-overlap)) !important;
108
+
109
+ /* 还原空间,防滚动条误触 */
110
+ padding-bottom: 0 !important;
111
+ margin-bottom: 0 !important;
112
+
113
+ overflow-y: auto !important;
114
+ scrollbar-width: thin;
115
+ }
116
+ }
117
+
118
+ /* =========================================================
119
+ 5. Admonition (提示框) 极简定制 - 四边等宽彩色边框
120
+ ========================================================= */
121
+ /* 基础容器:设置默认主色(Primary)边框,替代冗长的 :not() 兜底选择器 */
122
+ div.admonition {
123
+ border: 1px solid var(--pst-color-primary) !important;
124
+ border-radius: 0.25rem !important;
125
+ box-shadow: none !important;
126
+ }
127
+
128
+ /* 颜色语义精准映射(利用 CSS 层叠性自动覆盖上方默认的 Primary 颜色) */
129
+ div.admonition.note,
130
+ div.admonition.info,
131
+ div.admonition.hint {
132
+ border-color: var(--pst-color-info) !important;
133
+ }
134
+
135
+ div.admonition.tip,
136
+ div.admonition.success {
137
+ border-color: var(--pst-color-success) !important;
138
+ }
139
+
140
+ div.admonition.warning,
141
+ div.admonition.attention,
142
+ div.admonition.important,
143
+ div.admonition.caution {
144
+ border-color: var(--pst-color-warning) !important;
145
+ }
146
+
147
+ div.admonition.danger,
148
+ div.admonition.error {
149
+ border-color: var(--pst-color-danger) !important;
150
+ }
151
+
152
+ div.admonition.seealso {
153
+ border-color: var(--pst-color-secondary) !important;
154
+ }
155
+
156
+ /* =========================================================
157
+ 6. 修复:MathJax/Sphinx 公式垂直滚动条
158
+ remove this when pydata fix it!!
159
+ ========================================================= */
160
+ /* 1. 镇压 Sphinx 的外层容器 */
161
+ .bd-article div.math,
162
+ .bd-article div.math-wrapper,
163
+ div.math.notranslate {
164
+ overflow-x: auto !important;
165
+ overflow-y: hidden !important;
166
+ padding-top: 0.5em !important;
167
+ padding-bottom: 0.5em !important;
168
+ min-height: min-content !important;
169
+ }
170
+
171
+ /* 2. 镇压 MathJax 3 的原生渲染容器 */
172
+ mjx-container[display="true"],
173
+ .MathJax_Display {
174
+ overflow-y: hidden !important;
175
+ margin-top: 0 !important;
176
+ margin-bottom: 0 !important;
177
+ outline: none !important; /* 防止内部轮廓线撑破容器 */
178
+ }
179
+
180
+ /* 3. 镇压 MathJax 最深层的数学节点 */
181
+ mjx-container[display="true"] > mjx-math,
182
+ mjx-container[display="true"] > mjx-math * {
183
+ overflow-y: visible !important;
184
+ }
@@ -0,0 +1,8 @@
1
+ [theme]
2
+ inherit = pydata_sphinx_theme
3
+ # 覆盖或追加默认样式
4
+ stylesheet = css/zcnote_custom.css
5
+
6
+ [options]
7
+ # 新增的自定义配置项,默认开启侧边栏折叠
8
+ enable_collapse_sidebar = true
@@ -0,0 +1,47 @@
1
+ Metadata-Version: 2.4
2
+ Name: zcnote-sphinx-theme
3
+ Version: 0.0.1
4
+ Summary: A customized Sphinx theme based on pydata-sphinx-theme.
5
+ Author-email: zclab <yshi009@foxmail.com>
6
+ License-Expression: BSD-3-Clause
7
+ Project-URL: Source, https://github.com/zclab/zcnote-sphinx-theme
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Programming Language :: Python :: 3.10
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Programming Language :: Python :: 3.14
15
+ Classifier: Framework :: Sphinx
16
+ Classifier: Framework :: Sphinx :: Theme
17
+ Classifier: Operating System :: OS Independent
18
+ Requires-Python: >=3.10
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: sphinx<10,>=8.0
22
+ Requires-Dist: pydata-sphinx-theme<0.18.0,>=0.16.0
23
+ Provides-Extra: doc
24
+ Requires-Dist: sphinx_design; extra == "doc"
25
+ Requires-Dist: myst-parser; extra == "doc"
26
+ Requires-Dist: sphinx_copybutton; extra == "doc"
27
+ Requires-Dist: sphinx-togglebutton; extra == "doc"
28
+ Dynamic: license-file
29
+
30
+ # zcnote-sphinx-theme
31
+ A sphinx based on pydata-sphinx-theme
32
+
33
+
34
+ ## Installation and usage
35
+
36
+ To get started, firt install it with:
37
+ ```bash
38
+ python -m build
39
+ ```
40
+
41
+ then, activate the theme in your Sphinx configuration (conf.py):
42
+ ```python
43
+ html_theme = "zcnote_sphinx_theme"
44
+ ```
45
+
46
+ ## Documentation
47
+ See the zcnote sphinx theme documentation for more information.
@@ -0,0 +1,12 @@
1
+ zcnote_sphinx_theme/__init__.py,sha256=8YuLQfWOnTVKyJAUOu92Xbe-5wwX9YlRyy_qBNaAcOg,1119
2
+ zcnote_sphinx_theme/theme/zcnote_sphinx_theme/layout.html,sha256=50ZHhmRRBrBbjLlLWrcpfu62r5aP0Ea0p4mCWjcFUI0,5214
3
+ zcnote_sphinx_theme/theme/zcnote_sphinx_theme/theme.conf,sha256=9tOYtmOlzYnczjw6G36Jj998aKSFadYVjZpTZYKTRBI,205
4
+ zcnote_sphinx_theme/theme/zcnote_sphinx_theme/components/theme-version.html,sha256=N0yayDukJRkbhReelKIhVjW9XFUvmhwszRh6FbwF_4k,445
5
+ zcnote_sphinx_theme/theme/zcnote_sphinx_theme/static/css/zcnote_custom.css,sha256=FdGNObKXmkPzOg4UdNkrKakb0-FBiUNdxUQWbE0hSkQ,6112
6
+ zcnote_sphinx_theme/theme/zcnote_sphinx_theme/static/js/zcnote_custom.js,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
7
+ zcnote_sphinx_theme-0.0.1.dist-info/licenses/LICENSE,sha256=2S_GmGI4J9cgQTne54dPvXRH-SVrgZmsvXHPjuU9b2Q,1506
8
+ zcnote_sphinx_theme-0.0.1.dist-info/METADATA,sha256=BGU9rr1vVB0ieF3LKIJxP5vDLMhIQuREaNTja3Z8r1U,1487
9
+ zcnote_sphinx_theme-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
10
+ zcnote_sphinx_theme-0.0.1.dist-info/entry_points.txt,sha256=slkOrr1Ot-iv98M0zsmI1T9dQCniY-JPee5MSCgo9ys,63
11
+ zcnote_sphinx_theme-0.0.1.dist-info/top_level.txt,sha256=NHJMn9ydl8rnkJZpAvq9FuyH4V4w_GdUaAdQuhdxe8w,20
12
+ zcnote_sphinx_theme-0.0.1.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [sphinx.html_themes]
2
+ zcnote_sphinx_theme = zcnote_sphinx_theme
@@ -0,0 +1,29 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2018, pandas
4
+ All rights reserved.
5
+
6
+ Redistribution and use in source and binary forms, with or without
7
+ modification, are permitted provided that the following conditions are met:
8
+
9
+ * Redistributions of source code must retain the above copyright notice, this
10
+ list of conditions and the following disclaimer.
11
+
12
+ * Redistributions in binary form must reproduce the above copyright notice,
13
+ this list of conditions and the following disclaimer in the documentation
14
+ and/or other materials provided with the distribution.
15
+
16
+ * Neither the name of the copyright holder nor the names of its
17
+ contributors may be used to endorse or promote products derived from
18
+ this software without specific prior written permission.
19
+
20
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1 @@
1
+ zcnote_sphinx_theme