Debian Codegraph @

cmake/tribits/doc/build_ref/create-project-build-ref.py

raw
1 #!/usr/bin/env python3
2
3 usageHelp = r"""create-project-build-ref.py [options]
4
5 Generate a TriBITS project-specific build quick reference guide, typically
6 named <projectName>BuildReference.rst and output formats *.html and *.pdf (by
7 default). For the average TriBITS project-specific build quick reference
8 file, you just run this as::
9
10 $ cd <projectBaseDir>
11 $ ./cmake/tribits/doc/create-project-build-ref.py
12
13 (or run create-project-build-ref.py from where TriBITS is located for the
14 project). This will read the project's name from the file
15 <projectBaseDir>/ProjectName.cmake and will take the template file:
16
17 <projectBaseDir>/cmake/<projectName>BuildReferenceTemplate.rst
18
19 and the general TribitsBuildReferenceBody.rst input file and generate the
20 files:
21
22 <projectBaseDir>/
23 <projectName>BuildReference.rst
24 <projectName>BuildReference.html
25 <projectName>BuildReference.pdf
26
27 However, this script can be run to take any input template *.rst file
28 <projectTemplateFile> and any arbitrary project name and use it to generate
29 the specified output files. For an example of this, see the script:
30
31 tribits/doc/build_quick_ref/create-build-ref.sh
32
33 that creates a the files TribitsBuildReference.[rst,html,pdf]
34
35 """
36
37 import sys
38 import os
39 import stat
40 import subprocess
41
42 from optparse import OptionParser
43
44 #
45 # A) Set up basic paths and import modules
46 #
47
48 thisFilePath = __file__
49 thisFileRealAbsBasePath = \
50 os.path.dirname(os.path.abspath(os.path.realpath(thisFilePath)))
51 #print "thisFileRealAbsBasePath = '"+thisFileRealAbsBasePath+"'"
52
53 tribitsBaseDir = os.path.abspath(os.path.join(thisFileRealAbsBasePath, '../..'))
54 pythonUtilsDir = os.path.join(tribitsBaseDir, 'python_utils')
55 ciSupportDir = os.path.join(tribitsBaseDir, 'ci_support')
56
57 sys.path = [ciSupportDir, pythonUtilsDir] + sys.path
58 #print "sys.path =", sys.path
59
60 from GeneralScriptSupport import *
61 from CheckinTest import *
62 import GenerateDocUtilsOutput
63
64
65 #
66 # B) Read in the commandline options
67 #
68
69 clp = OptionParser(usage=usageHelp)
70
71 clp.add_option(
72 "--project-base-dir", dest="projectBaseDir", type="string",
73 default="",
74 help="Base directory of the TriBITS project <projectBaseDir>. If not set, is set"+\
75 " by default <tribitsBaseDir>/../.. which assumes that Tribits is under" \
76 " cmake/tribits in the current project. This option is not used if --project-name,"+\
77 " --project-template-file, and --file-base are all overridden."
78 )
79
80 clp.add_option(
81 "--project-name", dest="projectName", type="string",
82 default="",
83 help="If specified, then this will be ued for the project name (<projectName>."+\
84 " Otherwise, the project name is read from <projectBaseDir>/ProjectName.cmake instead."
85 )
86
87 clp.add_option(
88 "--project-template-file", dest="projectTemplateFile", type="string",
89 default="",
90 help="The project-specific template file used to generate the overall *.rst file."+\
91 " If not specified, then <projectBaseDir>/cmake/<projectName>BuildReferenceTemplate.rst"+\
92 " will be used instead."
93 )
94
95 clp.add_option(
96 "--min-cmake-version", dest="minCMakeVersion", type="string",
97 help="Minimum version of CMake needed for given project" \
98 " [Default '3.23.0']",
99 default="3.23.0" )
100
101 GenerateDocUtilsOutput.addCmndLineOptions(clp)
102
103 (options, args) = clp.parse_args(sys.argv)
104
105 #
106 # C) Get information for everything
107 #
108
109 if not options.projectBaseDir:
110 options.projectBaseDir = \
111 os.path.abspath(os.path.join(tribitsBaseDir, "../.."))
112 #print "projectBaseDir =", projectBaseDir
113
114 if not options.projectName:
115 options.projectName = getProjectName(options.projectBaseDir)
116 #print "projectName =", projectName
117
118 if not options.projectTemplateFile:
119 options.projectTemplateFile = \
120 os.path.join(options.projectBaseDir, "cmake", \
121 options.projectName+"BuildReferenceTemplate.rst")
122 #print "projectBuildReferenceTemplateFile =", projectBuildReferenceTemplateFile
123
124 if not options.fileBase:
125 options.fileBase = os.path.join(options.projectBaseDir,
126 options.projectName+"BuildReference")
127 #print "options.fileBase =", options.fileBase
128
129 #
130 # D) Read in standard body and make substitution
131 #
132
133 tribitsBuildReferenceBodyFile = \
134 os.path.join(thisFileRealAbsBasePath, "TribitsBuildReferenceBody.rst")
135 #print "tribitsBuildReferenceBodyFile =", tribitsBuildReferenceBodyFile
136
137 tribitsBuildReferenceBodyStr = \
138 readStrFromFile(tribitsBuildReferenceBodyFile)
139
140 substitutedTribitsBuildReferenceBodyStr = tribitsBuildReferenceBodyStr
141 substitutedTribitsBuildReferenceBodyStr = \
142 substitutedTribitsBuildReferenceBodyStr.replace("<Project>",
143 options.projectName)
144 substitutedTribitsBuildReferenceBodyStr = \
145 substitutedTribitsBuildReferenceBodyStr.replace("<MinCMakeVer>",
146 options.minCMakeVersion)
147
148 #
149 # E) Generate the output files
150 #
151
152 projectBuildReferenceTemplateStr = \
153 readStrFromFile(options.projectTemplateFile)
154
155 projectBuildReferenceStr = \
156 projectBuildReferenceTemplateStr \
157 + "\n\n" \
158 + substitutedTribitsBuildReferenceBodyStr
159
160 outputRstFile = options.fileBase+".rst"
161 print("Writing rst file ...")
162 GenerateDocUtilsOutput.openWriteFilePermissions(outputRstFile)
163 writeStrToFile(outputRstFile, projectBuildReferenceStr)
164 GenerateDocUtilsOutput.setGeneratedFilePermissions(outputRstFile)
165
166 GenerateDocUtilsOutput.generateDocutilsOuputFiles(options)