Skip to content

Commit 1ad146e

Browse files
ProdesireProdesire
committed
完善文档站点构建与部署
1 parent 0a584ed commit 1ad146e

11 files changed

Lines changed: 288 additions & 31 deletions

File tree

‎.github/workflows/pages.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Deploy documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- name: Checkout
24+
uses: actions/checkout@v4
25+
26+
- name: Set up Python
27+
uses: actions/setup-python@v5
28+
with:
29+
python-version: "3.8"
30+
31+
- name: Configure Pages
32+
uses: actions/configure-pages@v5
33+
34+
- name: Install dependencies
35+
run: make install
36+
37+
- name: Build documentation
38+
run: make html
39+
40+
- name: Upload Pages artifact
41+
uses: actions/upload-pages-artifact@v3
42+
with:
43+
path: docs/_build/html
44+
45+
deploy:
46+
environment:
47+
name: github-pages
48+
url: ${{ steps.deployment.outputs.page_url }}
49+
runs-on: ubuntu-latest
50+
needs: build
51+
52+
steps:
53+
- name: Deploy to GitHub Pages
54+
id: deployment
55+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,5 @@ build/
1818
.vscode
1919

2020
# virutal env
21-
venv/
21+
venv/
22+
.venv/

‎Makefile‎

Lines changed: 47 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,49 @@
1-
.PHONY: build
1+
.DEFAULT_GOAL := help
2+
3+
PYENV_PYTHON := $(shell if command -v pyenv >/dev/null 2>&1 && pyenv versions --bare | grep -qx '3.8.13'; then printf 'PYENV_VERSION=3.8.13 pyenv exec python'; fi)
4+
PYTHON ?= $(if $(PYENV_PYTHON),$(PYENV_PYTHON),python3)
5+
VENV ?= .venv
6+
PORT ?= 8005
7+
8+
VENV_BIN := $(VENV)/bin
9+
VENV_PYTHON := $(CURDIR)/$(VENV_BIN)/python
10+
SPHINXBUILD := $(CURDIR)/$(VENV_BIN)/sphinx-build
11+
BUILD_DIR := docs/_build
12+
INSTALL_STAMP := $(VENV)/.installed
13+
DOC_TARGETS := dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf latexpdfja text man texinfo info gettext changes linkcheck doctest xml pseudoxml netlify
14+
15+
.PHONY: help install build html serve clean $(DOC_TARGETS)
16+
17+
help:
18+
@echo "Please use \`make <target>' where <target> is one of"
19+
@echo " install create $(VENV) and install dependencies"
20+
@echo " html build standalone HTML files"
21+
@echo " serve build and serve docs at http://localhost:$(PORT)/"
22+
@echo " clean remove generated documentation files"
23+
@echo
24+
@echo "Other Sphinx targets are forwarded to docs/Makefile."
25+
26+
install: $(INSTALL_STAMP)
27+
28+
$(INSTALL_STAMP): requirements.txt
29+
@test -n "$(PYTHON)" || (echo "python3 is required" && exit 1)
30+
$(PYTHON) -m venv $(VENV)
31+
$(VENV_PYTHON) -m pip install --upgrade pip
32+
$(VENV_PYTHON) -m pip install -r requirements.txt
33+
@touch $(INSTALL_STAMP)
34+
235
build: html
336

4-
# this pattern rule lets you run "make build" (or any other target
5-
# in docs/Makefile) in this directory as though you were in docs/
6-
%:
7-
cd docs && make $@
37+
html: install
38+
$(MAKE) -C docs html SPHINXBUILD=$(SPHINXBUILD)
39+
@touch $(BUILD_DIR)/html/.nojekyll
40+
41+
serve: html
42+
cd $(BUILD_DIR)/html && $(VENV_PYTHON) -m http.server $(PORT)
43+
44+
clean:
45+
rm -rf $(BUILD_DIR)/*
46+
47+
# These targets let you run common docs/Makefile targets from the repository root.
48+
$(DOC_TARGETS): install
49+
$(MAKE) -C docs $@ SPHINXBUILD=$(SPHINXBUILD)

‎Readme.rst‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Python最佳实践指南中文版
1414

1515
项目翻译来自 `Hitchhiker's Guide to Python <https://github.com/kennethreitz/python-guide>`_。
1616

17-
Readthedocs文档地址 `Python最佳实践指南中文版 <http://pythonguidecn.readthedocs.org/>`_。
17+
GitHub Pages 文档地址 `Python最佳实践指南中文版 <https://prodesire.github.io/Python-Guide-CN/>`_。
1818

1919
-----------
2020

@@ -37,19 +37,20 @@ Readthedocs文档地址 `Python最佳实践指南中文版 <http://pythonguidecn
3737
- 测试: Jenkins & tox 指南
3838
- 如何更方便地通过 ``git`` 连接 ``hg``
3939

40-
如果您不习惯阅读reStructuredText形式的文档, 这里有一份同步更新的 `HTML版文档，请戳它 <http://pythonguidecn.readthedocs.org/>`_。
40+
如果您不习惯阅读reStructuredText形式的文档, 这里有一份同步更新的 `HTML版文档，请戳它 <https://prodesire.github.io/Python-Guide-CN/>`_。
4141

4242

4343
使用指南
4444
============================
4545
1. 下载zip文件或clone到本地，并进入到项目根目录
46-
2. 打开命令行，运行 ``pip install -r requirements.txt`` 安装依赖
47-
3. 打开命令行，运行 ``make html`` ; 或者（针对Windows）运行 ``makehtml.bat``
48-
4. 上述步骤自动在根目录下生成build文件夹，打开 ``./build/html/index.html`` 即可浏览文档
46+
2. 打开命令行，运行 ``make help`` 查看可用命令
47+
3. 打开命令行，运行 ``make install`` 创建虚拟环境并安装依赖
48+
4. 打开命令行，运行 ``make html`` 构建文档；或运行 ``make serve`` 构建并启动本地文档网站
49+
5. ``make html`` 会在 ``docs/_build/html`` 中生成 HTML 文件，``make serve`` 默认会在 ``http://localhost:8005/`` 运行文档网站
4950

5051
或者
5152
---------------------------
52-
- 直接访问 `Python最佳实践指南中文版 <http://pythonguidecn.readthedocs.org/>`_。
53+
- 直接访问 `Python最佳实践指南中文版 <https://prodesire.github.io/Python-Guide-CN/>`_。
5354

5455

5556
翻译指南
@@ -92,5 +93,3 @@ Support us by becoming a sponsor. Your logo will show up here with a link to you
9293
__ Sponsor_
9394

9495
.. _Sponsor: https://opencollective.com/python-guide-cn#sponsor
95-
96-

‎docs/404.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@
1111
- 使用了错误的地址
1212
- 使用了过期的链接
1313

14-
`点此返回主页 <http://pythonguidecn.readthedocs.io/zh/latest/>`_
14+
`点此返回主页 <https://prodesire.github.io/Python-Guide-CN/>`_
1515

16-
或者尝试 `搜索 <http://pythonguidecn.readthedocs.io/zh/latest/search.html>`_.
16+
或者尝试 `搜索 <https://prodesire.github.io/Python-Guide-CN/search.html>`_.
1717

1818
.. raw:: html
1919

‎docs/_static/github-star.css‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
.github-star {
2+
display: flex;
3+
align-items: center;
4+
justify-content: flex-start;
5+
height: 35px;
6+
margin: 0 auto 1em;
7+
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
8+
font-size: 16px;
9+
font-weight: 700;
10+
line-height: 22px;
11+
}
12+
13+
.github-star a {
14+
border-bottom: 0;
15+
}
16+
17+
.github-star__button,
18+
.github-star__count {
19+
box-sizing: border-box;
20+
color: #333;
21+
text-decoration: none;
22+
white-space: nowrap;
23+
border: 1px solid #d5d5d5;
24+
border-radius: 4px;
25+
}
26+
27+
.github-star__button {
28+
display: inline-flex;
29+
align-items: center;
30+
gap: 6px;
31+
padding: 3px 10px 3px 8px;
32+
background-color: #eee;
33+
background-image: linear-gradient(to bottom, #fcfcfc 0, #eee 100%);
34+
}
35+
36+
.github-star__button:hover,
37+
.github-star__button:focus,
38+
.github-star__count:hover,
39+
.github-star__count:focus {
40+
color: #0366d6;
41+
text-decoration: none;
42+
}
43+
44+
.github-star__button:hover,
45+
.github-star__button:focus {
46+
background-color: #ddd;
47+
background-image: linear-gradient(to bottom, #eee 0, #ddd 100%);
48+
border-color: #ccc;
49+
}
50+
51+
.github-star__icon {
52+
flex: 0 0 auto;
53+
}
54+
55+
.github-star__count {
56+
position: relative;
57+
display: inline-block;
58+
min-width: 56px;
59+
margin-left: 6px;
60+
padding: 3px 10px;
61+
text-align: center;
62+
background-color: #fafafa;
63+
border-color: #d4d4d4;
64+
}
65+
66+
.github-star__count::before,
67+
.github-star__count::after {
68+
position: absolute;
69+
top: 50%;
70+
display: inline-block;
71+
width: 0;
72+
height: 0;
73+
content: "";
74+
border-color: transparent;
75+
border-style: solid;
76+
}
77+
78+
.github-star__count::before {
79+
left: -5px;
80+
margin-top: -6px;
81+
border-width: 6px 6px 6px 0;
82+
border-right-color: #fafafa;
83+
}
84+
85+
.github-star__count::after {
86+
left: -6px;
87+
z-index: -1;
88+
margin-top: -7px;
89+
border-width: 7px 7px 7px 0;
90+
border-right-color: #d4d4d4;
91+
}

‎docs/_static/github-star.js‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
(function () {
2+
function formatCount(count) {
3+
return Number(count).toLocaleString("en-US");
4+
}
5+
6+
function updateStarCount(container, count) {
7+
var countLink = container.querySelector("[data-github-star-count]");
8+
if (!countLink) {
9+
return;
10+
}
11+
12+
var formattedCount = formatCount(count);
13+
countLink.textContent = formattedCount;
14+
countLink.setAttribute("aria-label", formattedCount + " stargazers on GitHub");
15+
}
16+
17+
Array.prototype.forEach.call(document.querySelectorAll("[data-github-star]"), function (container) {
18+
var repo = container.getAttribute("data-github-repo");
19+
if (!repo || !window.fetch) {
20+
return;
21+
}
22+
23+
window
24+
.fetch("https://api.github.com/repos/" + repo, {
25+
headers: {
26+
Accept: "application/vnd.github+json",
27+
},
28+
})
29+
.then(function (response) {
30+
if (!response.ok) {
31+
throw new Error("GitHub API request failed");
32+
}
33+
return response.json();
34+
})
35+
.then(function (repoData) {
36+
if (typeof repoData.stargazers_count === "number") {
37+
updateStarCount(container, repoData.stargazers_count);
38+
}
39+
})
40+
.catch(function () {
41+
// Keep the server-rendered fallback count visible when the API is unavailable.
42+
});
43+
});
44+
})();

‎docs/_templates/github_star.html‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<link rel="stylesheet" href="{{ pathto('_static/github-star.css', 1) }}" />
2+
<div class="github-star" data-github-star data-github-repo="Prodesire/Python-Guide-CN">
3+
<a
4+
class="github-star__button"
5+
href="https://github.com/Prodesire/Python-Guide-CN"
6+
rel="noopener noreferrer"
7+
target="_blank"
8+
aria-label="Star Prodesire/Python-Guide-CN on GitHub"
9+
>
10+
<svg
11+
class="github-star__icon"
12+
viewBox="0 0 16 16"
13+
width="16"
14+
height="16"
15+
aria-hidden="true"
16+
>
17+
<path
18+
fill="currentColor"
19+
d="M8 .25a8 8 0 0 0-2.53 15.59c.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82a7.65 7.65 0 0 1 4 0c1.53-1.03 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.19 0 .21.15.46.55.38A8 8 0 0 0 8 .25Z"
20+
/>
21+
</svg>
22+
<span>Star</span>
23+
</a>
24+
<a
25+
class="github-star__count"
26+
href="https://github.com/Prodesire/Python-Guide-CN/stargazers"
27+
rel="noopener noreferrer"
28+
target="_blank"
29+
aria-label="4,420 stargazers on GitHub"
30+
data-github-star-count
31+
>4,420</a>
32+
</div>
33+
<script src="{{ pathto('_static/github-star.js', 1) }}" defer></script>

‎docs/_templates/sidebarintro.html‎

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,7 @@
88
</a>
99
</p>
1010

11-
<p style="margin-left:auto; margin-right: auto;">
12-
<iframe
13-
src="https://ghbtns.com/github-btn.html?user=prodesire&repo=python-guide-cn&type=watch&count=true&size=large"
14-
allowtransparency="true"
15-
frameborder="0"
16-
scrolling="0"
17-
width="200px"
18-
height="35px"
19-
></iframe>
20-
</p>
11+
{% include "github_star.html" %}
2112

2213
<link
2314
rel="stylesheet"
@@ -116,7 +107,7 @@ <h3>翻译</h3>
116107
<li>
117108
<a href="https://python-guide-fr.readthedocs.io/fr/latest/">French</a>
118109
</li>
119-
<li><a href="https://pythonguidecn.readthedocs.io/zh/latest/">Chinese</a></li>
110+
<li><a href="https://prodesire.github.io/Python-Guide-CN/">Chinese</a></li>
120111
<li>
121112
<a href="https://python-guideja.readthedocs.io/ja/latest/">Japanese</a>
122113
</li>

‎docs/_templates/sidebarlogo.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
</a>
55
</p>
66

7-
<p style="margin-left:auto; margin-right: auto;"><iframe src="https://ghbtns.com/github-btn.html?user=prodesire&repo=python-guide-cn&type=watch&count=true&size=large" allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe></p>
7+
{% include "github_star.html" %}
88

99
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />
1010
<style>
@@ -49,7 +49,7 @@ <h3>翻译</h3>
4949
<ul>
5050
<li><a href="https://docs.python-guide.org/en/latest/">English</a></li>
5151
<li><a href="https://python-guide-fr.readthedocs.io/fr/latest/">French</a></li>
52-
<li><a href="https://pythonguidecn.readthedocs.io/zh/latest/">Chinese</a></li>
52+
<li><a href="https://prodesire.github.io/Python-Guide-CN/">Chinese</a></li>
5353
<li><a href="http://python-guideja.readthedocs.io/ja/latest/">Japanese</a></li>
5454
<li><a href="https://python-guide-kr.readthedocs.io/ko/latest/">Korean</a></li>
5555
<li><a href="http://python-guide-fil.readthedocs.io/en/latest/">Filipino</a></li>

0 commit comments

Comments
 (0)