Debian Codegraph @

cmake/tribits/doc/guides/generate-guide.sh

raw
1 #!/bin/bash
2
3 # This script is used to generate the TribitsUsersGuide.(html,pdf) and
4 # TribitsMaintainersGuide.html files. You just run it from this directory as:
5 #
6 # cd <this-dir>
7 # ./generate-guide.sh all
8 #
9 # To just generate the users guide, run:
10 #
11 # ./generate-guide.sh ug
12 #
13 # To just generate the maintainers guide, run:
14 #
15 # ./generate-guide.sh mg
16 #
17 # This script automatically extracts detailed TriBITS documentation from the
18 # *.cmake files using the tool extract_rst_cmake_doc.py (which works kind of
19 # like doxygen). To see output from extract_rst_cmake_doc.py just run the
20 # script as:
21 #
22 # $ env TRIBITS_DEV_GUIDE_EXTRACT_RST_CMAKE_DOC_EXTRA_ARGS=--do-trace \
23 # ./generate-guide.sh all
24 #
25 # NOTE: If you see rst2html or rst2latex errors in the files
26 # TribitsUsersGuide.rst or TribitsMaintainersGuide.rst with line numbers that
27 # don't seem to make sense, this is likely due to the include of
28 # TribitsDetailedMacroFunctionDoc.rst. To adjust the line numbers, subtract
29 # the line number of the include for TribitsDetailedMacroFunctionDoc.rst in
30 # TribitsUsersGuide.rst or TribitsMaintainersGuide.rst from the line number
31 # given in the output and that will be the line number in the file
32 # TribitsUsersGuide.rst or TribitsMaintainersGuide.rst. You can then match
33 # that up with the original text in the *.cmake file that this came from for
34 # the given macro or function.
35 #
36 # NOTE: To skip the extraction of the documentation from the *.cmake files,
37 # just sent the env TRIBITS_DEV_GUIDE_SKIP_DOCUMENTATION_EXTRACTION variable
38 # as:
39 #
40 # $ env TRIBITS_DEV_GUIDE_SKIP_DOCUMENTATION_EXTRACTION=1 \
41 # ./generate-guide.sh
42 #
43 # That will result in the generated files TribitsMacroFunctionDoc.rst and
44 # UtilsMacroFunctionDoc.rst being left as is. This would be useful to speed
45 # up builds (it is very fast) but is more useful when spell checking and
46 # editing the documentation. This speeds up the editing process and then the
47 # updated documentation can be copied back into the *.cmake files of origin.
48 #
49 # Enjoy!
50 #
51
52
53 #
54 # Parse command-line arguments
55 #
56
57 generate_maintainers_guide=0
58 generate_users_guide=0
59 skip_final_generation=0
60
61 while (( "$#" )); do
62 case "$1" in
63 mg|maintainers_guide)
64 generate_maintainers_guide=1
65 shift
66 ;;
67 ug|users_guide)
68 generate_users_guide=1
69 shift
70 ;;
71 all)
72 generate_maintainers_guide=1
73 generate_users_guide=1
74 shift
75 ;;
76 --skip-final-generation)
77 skip_final_generation=1
78 shift
79 ;;
80 *)
81 echo "Error: The argument '$1' is not supported!"
82 exit 1
83 ;;
84 esac
85 done
86
87
88 #
89 # Functions
90 #
91
92 source ../utils/gen_doc_utils.sh
93
94
95 function generate_gitdist_dist_help_topic {
96 help_topic_name=$1
97 ../../python_utils/gitdist --dist-help=$help_topic_name &> gitdist-dist-help-$help_topic_name.txt.tmp
98 update_if_different gitdist-dist-help-$help_topic_name.txt tmp
99 }
100
101
102 function tribits_extract_rst_cmake_doc {
103 dir=$1
104 extra_args=$2
105
106 cd ${dir}
107 echo $PWD
108
109 if [ "$TRIBITS_DEV_GUIDE_SKIP_DOCUMENTATION_EXTRACTION" == "" ] ; then
110
111 echo
112 echo "Extracting TriBITS documentation from *.cmake files ..."
113 echo
114 ../../../python_utils/extract_rst_cmake_doc.py \
115 --extract-from=../../../ctest_driver/,../../../ci_support/,../../../core/package_arch/,../../../core/test_support/,../../../core/utils/ \
116 --rst-file-pairs=../TribitsMacroFunctionDocTemplate.rst:TribitsMacroFunctionDoc.rst.tmp,../UtilsMacroFunctionDocTemplate.rst:UtilsMacroFunctionDoc.rst.tmp,../TribitsSystemMacroFunctionDocTemplate.rst:TribitsSystemMacroFunctionDoc.rst.tmp \
117 ${extra_args} \
118 --file-name-path-base-dir=../../.. \
119 $TRIBITS_DEV_GUIDE_EXTRACT_RST_CMAKE_DOC_EXTRA_ARGS
120
121 update_if_different TribitsMacroFunctionDoc.rst tmp
122 update_if_different UtilsMacroFunctionDoc.rst tmp
123 update_if_different TribitsSystemMacroFunctionDoc.rst tmp
124
125 fi
126
127 cd -
128
129 }
130
131
132 function tribits_extract_other_doc {
133
134 if [ "$TRIBITS_DEV_GUIDE_SKIP_OTHER_EXTRACTION" == "" ] ; then
135
136 echo
137 echo "Generating list of Standard TriBITS TPLs ..."
138 echo
139 ls -w 1 ../../core/std_tpls/ &> TribitsStandardTPLsList.txt.tmp
140 update_if_different TribitsStandardTPLsList.txt tmp
141
142 echo
143 echo "Generating list of Common TriBITS TPLs ..."
144 echo
145 ls -w 1 ../../common_tpls/ &> TribitsCommonTPLsList.txt.tmp
146 update_if_different TribitsCommonTPLsList.txt tmp
147
148 echo
149 echo "Generating Directory structure of TribitsHelloWorld ..."
150 echo
151 ../../python_utils/tree.py -f -c -x ../../examples/TribitsHelloWorld/ \
152 &> TribitsHelloWorldDirAndFiles.txt.tmp
153 update_if_different TribitsHelloWorldDirAndFiles.txt tmp
154
155 echo
156 echo "Generating TribitsExampleProject2/Package1 CMakeList file variants ..."
157 echo
158
159 cat ../../examples/TribitsExampleProject2/packages/package1/CMakeLists.raw.cmake \
160 | grep -v EnableTribitsTestSupport \
161 | grep -v GeneratePackageConfigFileForBuildDir \
162 &> TribitsExampleProject2_Package1_CMakeLists.raw.external.cmake.tmp
163 update_if_different TribitsExampleProject2_Package1_CMakeLists.raw.external.cmake tmp
164
165 cat ../../examples/TribitsExampleProject2/packages/package1/CMakeLists.raw.cmake \
166 | grep -v EnableTribitsTestSupport \
167 &> TribitsExampleProject2_Package1_CMakeLists.raw.internal.cmake.tmp
168 update_if_different TribitsExampleProject2_Package1_CMakeLists.raw.internal.cmake tmp
169
170 cat ../../examples/TribitsExampleProject2/packages/package1/CMakeLists.raw.cmake \
171 | grep -v "that TriBITS does automatically" \
172 | grep -v DefineAllLibsTarget \
173 | grep -v GeneratePackageConfigFileForBuildDir \
174 | grep -v GeneratePackageConfigFileForInstallDir \
175 &> TribitsExampleProject2_Package1_CMakeLists.raw.tribits_test.cmake.tmp
176 update_if_different \
177 TribitsExampleProject2_Package1_CMakeLists.raw.tribits_test.cmake tmp
178
179 echo
180 echo "Generating output for 'checkin-test.py --help' ..."
181 echo
182 ../../ci_support/checkin-test.py --help &> checkin-test-help.txt.tmp
183 update_if_different checkin-test-help.txt tmp
184
185 echo
186 echo "Generating output for 'gitdist --help' and '--dist-help=<topic>' ..."
187 echo
188 ../../python_utils/gitdist --help &> gitdist-help.txt.tmp
189 update_if_different gitdist-help.txt tmp
190 generate_gitdist_dist_help_topic overview
191 generate_gitdist_dist_help_topic repo-selection-and-setup
192 generate_gitdist_dist_help_topic dist-repo-status
193 generate_gitdist_dist_help_topic repo-versions
194 generate_gitdist_dist_help_topic aliases
195 generate_gitdist_dist_help_topic default-branch
196 generate_gitdist_dist_help_topic move-to-base-dir
197 generate_gitdist_dist_help_topic usage-tips
198 generate_gitdist_dist_help_topic script-dependencies
199 generate_gitdist_dist_help_topic all
200
201 echo
202 echo "Generating output for 'clone_extra_repos.py --help' ..."
203 echo
204 ../../ci_support/clone_extra_repos.py --help \
205 &> clone_extra_repos-help.txt.tmp
206 update_if_different clone_extra_repos-help.txt tmp
207
208 echo
209 echo "Generating output for 'snapshot-dir.py --help' ..."
210 echo
211 env SNAPSHOT_DIR_DUMMY_DEFAULTS=1 ../../python_utils/snapshot-dir.py --help \
212 &> snapshot-dir-help.txt.tmp
213 update_if_different snapshot-dir-help.txt tmp
214
215 echo
216 echo "Generating output for 'is_checkin_tested_commit.py --help' ..."
217 echo
218 ../../ci_support/is_checkin_tested_commit.py --help \
219 &> is_checkin_tested_commit.txt.tmp
220 update_if_different is_checkin_tested_commit.txt tmp
221
222 echo
223 echo "Generating output for 'get-tribits-packages-from-files-list.py --help' ..."
224 echo
225 ../../ci_support/get-tribits-packages-from-files-list.py --help \
226 &> get-tribits-packages-from-files-list.txt.tmp
227 update_if_different get-tribits-packages-from-files-list.txt tmp
228
229 echo
230 echo "Generating output for 'get-tribits-packages-from-last-tests-failed.py --help' ..."
231 echo
232 ../../ci_support/get-tribits-packages-from-last-tests-failed.py --help \
233 &> get-tribits-packages-from-last-tests-failed.txt.tmp
234 update_if_different get-tribits-packages-from-last-tests-failed.txt tmp
235
236 echo
237 echo "Generating output for 'filter-packages-list.py --help' ..."
238 echo
239 ../../ci_support/filter-packages-list.py --help \
240 &> filter-packages-list.txt.tmp
241 update_if_different filter-packages-list.txt tmp
242
243 echo
244 echo "Generating output for 'install_devtools.py --help' ..."
245 echo
246 ../../devtools_install/install_devtools.py --help \
247 &> install_devtools-help.txt.tmp
248 update_if_different install_devtools-help.txt tmp
249
250 fi
251
252 if [ -e "../../../README.DIRECTORY_CONTENTS.rst" ] ; then
253 echo
254 echo "Copy TriBITS/README.DIRECTORY_CONTENTS.rst to TriBITS.README.DIRECTORY_CONTENTS.rst ..."
255 echo
256 cp ../../../README.DIRECTORY_CONTENTS.rst TriBITS.README.DIRECTORY_CONTENTS.rst.tmp
257 else
258 echo
259 echo "TriBITS/README.DIRECTORY_CONTENTS.rst does not exist to copy!"
260 echo
261 touch TriBITS.README.DIRECTORY_CONTENTS.rst.tmp
262 fi
263 update_if_different TriBITS.README.DIRECTORY_CONTENTS.rst tmp
264
265 }
266
267
268 function make_final_doc_in_subdir {
269 dir_name=$1
270 if [[ "${skip_final_generation}" == "0" ]] ; then
271 cd $dir_name
272 echo $PWD
273 time make
274 cd - > /dev/null
275 else
276 echo
277 echo "Skipping final generation of '${dir_name}' on request!"
278 echo
279 fi
280 }
281
282
283 #
284 # Executable code
285 #
286
287 generate_git_version_file
288
289 tribits_extract_other_doc
290
291 if [[ "${generate_users_guide}" == "1" ]] ; then
292
293 echo
294 echo "Generating HTML and PDF files for users guide ..."
295 echo
296
297 tribits_extract_rst_cmake_doc users_guide
298
299 make_final_doc_in_subdir users_guide
300
301 fi
302
303 if [[ "${generate_maintainers_guide}" == "1" ]] ; then
304
305 echo
306 echo "Generating HTML file for maintainers_guide ..."
307 echo
308
309 tribits_extract_rst_cmake_doc maintainers_guide --show-file-name-line-num
310
311 make_final_doc_in_subdir maintainers_guide
312
313 fi