-
Notifications
You must be signed in to change notification settings - Fork 9
/
build_docs.sh
executable file
·210 lines (161 loc) · 6.43 KB
/
build_docs.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
#!/bin/bash
# This shell script builds the docs for msiempy
# I've been running it from MacOS but I beleive it's valid on Linux too.
# It will automatically generate pydoctor documentation coupled with mkdocs to show different versions
# It also adds git reference and tag info
# Will first write the docs under the version's folder, and then overwrites default (lastest in the root folder).
# See the mkdocs site under ./site folder
# Then it will copy the content to your storage location: if passed with -o <path>
# The storage should not be deleted and you should use the same storage for all versions. ./site will still contain the genrated site
# The 'index.md' files under './docs/<version>/index.md' should be kept in the repo for mkdocs to ba able to generate the navbar with different versions.
# Requirements: graphviz, pydoctor mkdocs mkdocs-awesome-pages-plugin
# Install python requirements
# python3 setup.py install
# python3 -m pip install -r requirements.txt
# sudo apt-get install graphviz || sudo yum install graphviz || brew install graphviz
# Usage ./build_docs "./mfesiem.github.io/docs/test/msiempy"
# Stop if errors
set -euo pipefail
IFS=$'\n\t,'
usage(){
echo "[USAGE] $0 [-h] [-o <path>] [-f]" 1>&2
echo
echo "This shell script builds the docs for msiempy. Generates the mkdocs site under './site' folder, allows versionning and include a few handy options. Unix only. "
echo
echo -e "\t-h\tPrint this help message."
echo -e "\t-o\t<path>\tStorage location. The content of the mkdocs+pydoctor site will be copied to this folder. './site' folder will still contain the genrated site. "
echo -e "\t-f\t\tOverwrite the existing 'index.md' files located in the './docs/<version>' folder. Default behaviour will quit if './docs/<version>/index.md' already exists. "
echo -e "\t-d\t\tDevelopment mode: do not write under './docs/<version>' but directly to './docs' only. Default behaviour will write to './docs/<version>' "
echo -e "\t-i\t\tGenerate only the './docs/<version>/index.md' file and exit. "
exit -1
}
function restore_docs_folder()
{
# Restore docs folder
if [[ -d ./docs-tmp ]]; then
rm -rf ./docs
cp -r ./docs-tmp ./docs
rm -rf ./docs-tmp
fi
}
trap restore_docs_folder EXIT
multi_version_site=""
force=false
devel=false
index_only=false
while getopts ":ho:fdi" arg; do
case "${arg}" in
h) #Print help
usage
;;
o)
# The out folder # This should be sychronized with alternative storage.
multi_version_site=${OPTARG}
mkdir -p "${multi_version_site}"
;;
f)
force=true
;;
d)
devel=true
;;
i)
index_only=true
;;
*)
echo "[ERROR] Syntax mistake calling the script."
usage
exit
;;
esac
done
# Figure the project version
project_version="$(python3 setup.py -V)"
# Figure commit ref
git_sha="$(git rev-parse HEAD)"
if ! git describe --exact-match --tags; then
tag="Warning: Not a tagged version."
is_tag=0
else
git_sha="$(git describe --exact-match --tags)"
tag="Tag: ${git_sha}."
is_tag=1
fi
# Folder i.e. ./docs/0.3.5/
if ! [[ ${devel} = true ]]; then
docs_folder="./docs/${project_version}"
else
docs_folder="./docs"
fi
# Create the docs folder if it doesn't exists
if [ -e "${docs_folder}/index.md" ]; then
if ! [[ ${force} = true ]]; then
echo "[ERROR] An 'index.md' already exists in ${docs_folder}. Use -f to overwrite. "
exit 1
fi
else
mkdir -p "${docs_folder}"
fi
#Figure out branch
branch=$(git rev-parse --abbrev-ref HEAD)
# Include readme
readme=$(cat ./README.md)
# Autogenerated index
echo "# msiempy ${project_version}
<!-- The mkdocs index to should show msiempy version in the header -->
<!-- This file should not be directly edited, edit the script build_docs.sh instead -->
*This is an autogenerated index for [msiempy](https://github.com/mfesiem/msiempy/) version ${project_version}, git reference [${git_sha}](https://github.com/mfesiem/msiempy/tree/${git_sha})*.
*${tag}*
*Generated from branch ${branch}, on the $(date).*
# Documentation summary
**[View the Python API Reference](msiempy.html)**
Or navigate:
- A listing of [all modules and packages](moduleIndex.html), organized by package hierarchy.
- A listing of [all classes](classIndex.html), organized by inheritance hierarchy.
- A listing of [all functions, classes, modules and packages](nameIndex.html), ordered by name.
For more exemples, see the [samples folder](https://github.com/mfesiem/msiempy/tree/master/samples) or
the [tests](https://github.com/mfesiem/msiempy/tree/master/tests) for other scripts.
See also:
- [Class diagram](classes.png), ([Packages diagram](packages.png))
- [mfesiem.github.io](https://mfesiem.github.io) (generated PDFs and other links)
(*Links are relative*)
***
Back to [GitHub | README](https://github.com/mfesiem/msiempy/)
" > "${docs_folder}/index.md"
echo "[INFO] Write docs index to ${docs_folder}/index.md "
if [[ ${index_only} = true ]]; then
exit 0
fi
# Backup docs folder right after creating index.md. Only index.md should be kept here
if [[ -d ./docs ]]; then
cp -r docs docs-tmp
fi
# Generate diagrams under the ./docs/version folder
pyreverse -s 1 -f PUB_ONLY -o png -m y msiempy
mv ./classes.png "${docs_folder}"
mv ./packages.png "${docs_folder}"
# Generate
python3 ./samples/list_request_args.py > "./all_request_args.rst"
# Run pydoctor build, just before the mkdocs build
# The index.html will be overwritten
pydoctor \
--add-package=msiempy \
--project-name="msiempy" \
--html-viewsource-base="https://github.com/mfesiem/msiempy/tree/${git_sha}" \
--make-html \
--project-base-dir="$(pwd)" \
--docformat=restructuredtext \
--intersphinx=https://docs.python.org/3/objects.inv \
--html-output="${docs_folder}" || true
# Copy the docs from the versionned folder to the latest (root folder). Only if not already there.
if ! [ ${docs_folder} = "./docs" ] ; then
cp -rf ${docs_folder}/* "./docs"
fi
# Run mkdocs build, will overwrite pydoctor index.html files
mkdocs build
# Copy the docs in the versionned folder to the site with multiples versions
if [[ -n "${multi_version_site}" ]]; then
cp -r ./site/* "${multi_version_site}"
echo "[INFO] Site content copied to: ${multi_version_site}"
fi
restore_docs_folder