Skip to content

Commit feee7bb

Browse files
NeoZhangJianyuarthw
NeoZhangJianyu
and
arthw
authored
refactor online doc build script to support update latest online doc … (#2318)
Co-authored-by: ZhangJianyu <[email protected]>
1 parent 1429a4a commit feee7bb

18 files changed

+500
-219
lines changed

‎.github/workflows/publish.yml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Publish
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
build:
10+
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- uses: actions/checkout@v3
15+
- name: Build Online Document
16+
run: |
17+
git config --local --get remote.origin.url
18+
cd docs/build_docs
19+
bash build.sh latest
20+
21+
- name: Push to github
22+
uses: peaceiris/actions-gh-pages@v3
23+
with:
24+
github_token: ${{ secrets.GITHUB_TOKEN }}
25+
publish_dir: ./build_tmp/gh-pages
26+
publish_branch: gh-pages
27+

‎conf.py

Lines changed: 0 additions & 83 deletions
This file was deleted.

‎Makefile renamed to ‎docs/build_docs/Makefile

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
# from the environment for the first two.
66
SPHINXOPTS ?=
77
SPHINXBUILD ?= sphinx-build
8-
SOURCEDIR = .
8+
SOURCEDIR = source
99
BUILDDIR = build
1010

1111
# Put it first so that "make" without argument is like "make help".
@@ -14,11 +14,7 @@ help:
1414

1515
.PHONY: help Makefile
1616

17-
html:
18-
$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
19-
cp docs/docs_build/_static/index.html $(BUILDDIR)/html/index.html
20-
mkdir "$(BUILDDIR)/html/docs/guide/images"
21-
cp docs/guide/images/* "$(BUILDDIR)/html/docs/guide/images"
22-
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
2319
%: Makefile
2420
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/build_docs/build.sh

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
#i!/bin/bash
2+
3+
help () {
4+
echo ""
5+
echo "Help:"
6+
echo "$0 or $0 local"
7+
echo " Build html for local test, not merge to gh-pages branch"
8+
echo "$0 version"
9+
echo " Build for version (version.py), then merge & push to gh-pages branch"
10+
echo "$0 latest"
11+
echo " Build for latest code, then merge & push to gh-pages branch"
12+
}
13+
14+
if [ ! -n "$1" ]; then
15+
ACT=only_build_local
16+
else
17+
if [ "$1" == "version" ]; then
18+
ACT=build_version
19+
elif [ "$1" == "latest" ]; then
20+
ACT=build_latest
21+
elif [ "$1" == "local" ]; then
22+
ACT=only_build_local
23+
elif [ "$1" == "help" ]; then
24+
help
25+
exit 0
26+
else
27+
echo "Wrong parameter \"$1\""
28+
help
29+
exit 1
30+
fi
31+
fi
32+
33+
echo "ACT is ${ACT}"
34+
35+
if [ ${ACT} == "only_build_local" ]; then
36+
UPDATE_LATEST_FOLDER=1
37+
UPDATE_VERSION_FOLDER=1
38+
CHECKOUT_GH_PAGES=0
39+
elif [ ${ACT} == "build_version" ]; then
40+
UPDATE_LATEST_FOLDER=0
41+
UPDATE_VERSION_FOLDER=1
42+
CHECKOUT_GH_PAGES=1
43+
elif [ ${ACT} == "build_latest" ]; then
44+
UPDATE_LATEST_FOLDER=1
45+
UPDATE_VERSION_FOLDER=0
46+
CHECKOUT_GH_PAGES=1
47+
fi
48+
49+
WORK_DIR=../../build_tmp
50+
rm -rf /tmp/env_sphinx
51+
if [ ! -d ${WORK_DIR} ]; then
52+
echo "no ${WORK_DIR}"
53+
54+
else
55+
if [ ! -d ${WORK_DIR}/env_sphinx ]; then
56+
echo "no exist ${WORK_DIR}/env_sphinx"
57+
else
58+
cp -rf ${WORK_DIR}/env_sphinx /tmp/
59+
rm -rf ${WORK_DIR}
60+
echo "backup ${WORK_DIR}/env_sphinx to /tmp"
61+
fi
62+
fi
63+
64+
mkdir -p ${WORK_DIR}
65+
cp -rf ./* ${WORK_DIR}
66+
67+
cd ${WORK_DIR}
68+
69+
if [ ! -d /tmp/env_sphinx ]; then
70+
echo "no /tmp/env_sphinx"
71+
else
72+
echo "restore env_sphinx from /tmp"
73+
cp -r /tmp/env_sphinx ./
74+
fi
75+
76+
if [ ! -d env_sphinx ]; then
77+
echo "create env_sphinx"
78+
bash pip_set_env.sh
79+
fi
80+
81+
source env_sphinx/bin/activate
82+
echo `pwd`
83+
cp -rf ../docs/ ./source
84+
cp -rf ../docker/ ./source
85+
cp -f "../README.md" "./source/get_started.md"
86+
cp -rf "../examples" "./source/"
87+
cp -f "../SECURITY.md" "./source/"
88+
cp -f "../LICENSE.txt" "./source/"
89+
cp -f "../CODE_OF_CONDUCT.md" "./source/"
90+
#sed -i 's/docs\/guide/guide/g' ./source/docs/get_started.md
91+
92+
sed -i 's/.md/.html/g' ./source/get_started.md
93+
sed -i 's/.md/.html/g' ./source/docs/install/experimental/install_for_cpp.md
94+
95+
sed -i 's/pluggable-device-for-tensorflow.html/pluggable-device-for-tensorflow.md/g' ./source/get_started.md
96+
sed -i 's/third-party-programs\/THIRD-PARTY-PROGRAMS/https:\/\/github.com\/intel\/intel-extension-for-tensorflow\/blob\/main\/third-party-programs\/THIRD-PARTY-PROGRAMS/g' ./source/get_started.md
97+
sed -i 's/# Intel® Extension for TensorFlow*/# Quick Get Started/g' ./source/get_started.md
98+
99+
100+
make clean
101+
make html
102+
103+
if [[ $? -eq 0 ]]; then
104+
echo "Sphinx build online documents successfully!"
105+
else
106+
echo "Sphinx build online documents fault!"
107+
exit 1
108+
fi
109+
110+
DRAFT_FOLDER=./draft
111+
mkdir -p ${DRAFT_FOLDER}
112+
VERSION=`cat source/version.txt`
113+
DST_FOLDER=${DRAFT_FOLDER}/${VERSION}
114+
LATEST_FOLDER=${DRAFT_FOLDER}/latest
115+
SRC_FOLDER=build/html
116+
117+
RELEASE_FOLDER=./gh-pages
118+
ROOT_DST_FOLDER=${RELEASE_FOLDER}/${VERSION}
119+
ROOT_LATEST_FOLDER=${RELEASE_FOLDER}/latest
120+
121+
cp2html() {
122+
SRC_FOLDER=$1
123+
DST_FOLDER=$2
124+
VERSION=$3
125+
echo "create ${DST_FOLDER}"
126+
rm -rf ${DST_FOLDER}/*
127+
mkdir -p ${DST_FOLDER}
128+
cp -r ${SRC_FOLDER}/* ${DST_FOLDER}
129+
python update_html.py ${DST_FOLDER} ${VERSION}
130+
cp -r ./source/docs/guide/images ${DST_FOLDER}/docs/guide
131+
cp ./source/LICENSE.txt ${DST_FOLDER}/
132+
#cp -r ./source/docs/source/neural_coder/extensions/neural_compressor_ext_vscode/images ${DST_FOLDER}/docs/source/neural_coder/extensions/neural_compressor_ext_vscode
133+
#cp -r ./source/docs/source/neural_coder/extensions/screenshots ${DST_FOLDER}/docs/source/neural_coder/extensions
134+
135+
cp source/_static/index.html ${DST_FOLDER}
136+
}
137+
if [[ ${UPDATE_VERSION_FOLDER} -eq 1 ]]; then
138+
cp2html ${SRC_FOLDER} ${DST_FOLDER} ${VERSION}
139+
else
140+
echo "skip to create ${DST_FOLDER}"
141+
fi
142+
143+
if [[ ${UPDATE_LATEST_FOLDER} -eq 1 ]]; then
144+
cp2html ${SRC_FOLDER} ${LATEST_FOLDER} ${VERSION}
145+
else
146+
echo "skip to create ${LATEST_FOLDER}"
147+
fi
148+
149+
echo "Create document is done"
150+
151+
if [[ ${CHECKOUT_GH_PAGES} -eq 1 ]]; then
152+
GITHUB_URL=`git config --get remote.origin.url`
153+
git clone -b gh-pages --single-branch ${GITHUB_URL} ${RELEASE_FOLDER}
154+
155+
if [[ ${UPDATE_VERSION_FOLDER} -eq 1 ]]; then
156+
python update_version.py ${ROOT_DST_FOLDER} ${VERSION}
157+
cp -rf ${DST_FOLDER} ${RELEASE_FOLDER}
158+
fi
159+
160+
if [[ ${UPDATE_LATEST_FOLDER} -eq 1 ]]; then
161+
cp -rf ${LATEST_FOLDER} ${RELEASE_FOLDER}
162+
fi
163+
164+
else
165+
echo "skip pull gh-pages"
166+
fi
167+
168+
echo "UPDATE_LATEST_FOLDER=${UPDATE_LATEST_FOLDER}"
169+
echo "UPDATE_VERSION_FOLDER=${UPDATE_VERSION_FOLDER}"
170+
171+
172+
if [[ $? -eq 0 ]]; then
173+
echo "create online documents successfully!"
174+
else
175+
echo "create online documents fault!"
176+
exit 1
177+
fi
178+
179+
exit 0

‎docs/build_docs/docs_build_tips.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Online Documentation Build Guide
2+
3+
4+
## Introduction
5+
6+
This document shows how scripts are used to build the project documentation.
7+
8+
The scripts and related files are saved in the `docs/build_docs` directory.
9+
10+
11+
## Update `latest` Version
12+
13+
Generating and publishing the `latest` documentation is triggered by merging a PR to the public GitHub repo's main branch. A GitHub `Action` executes the document-building scripts using content from the main branch and updates the `latest` [published version](https://intel.github.io/intel-extension-for-tensorflow/latest/get_started.html).
14+
15+
If the PR doesn't impact documentation (for example, it only contains code changes), the online documents won't be updated.
16+
17+
## Create Release Version
18+
19+
When releasing a new product version, a git tag must be added to main branch. The release version will be the same as the `tag` name.
20+
21+
It needs to be triggered and commit to branch `gh-pages` manually.
22+
23+
`
24+
git clone https://github.com/intel/intel-extension-for-tensorflow.git
25+
git checkout tag??
26+
cd intel-extension-for-tensorflow/docs/build_docs
27+
./build.sh version
28+
29+
cd ../../build_tmp/gh-pages
30+
git add .
31+
git commit -m "add version ???"
32+
git push
33+
`
34+
35+
## Build to Local Test
36+
37+
```
38+
git clone https://github.com/intel/intel-extension-for-tensorflow.git
39+
change code??
40+
cd intel-extension-for-tensorflow/docs/build_docs
41+
42+
./build.sh local
43+
cd ../../build_tmp/draft/latest
44+
python3 -m http.server 9000
45+
```
46+
47+
Use Chrome to open '127.0.0.1:9000' to check the latest version documents.
48+
49+
Note, the 'version.html' is not present in this case for latest version.
50+
51+
If you want to test version switching functionality using `version.html`, build for `version`:
52+
53+
```
54+
git clone https://github.com/intel/intel-extension-for-tensorflow.git
55+
# make your documentation changes
56+
cd intel-extension-for-tensorflow/docs/build_docs
57+
58+
./build.sh version
59+
cd ../../build_tmp/gh-pages/tag??
60+
python3 -m http.server 9000
61+
62+
```

0 commit comments

Comments
 (0)