| 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) |