release_docs.py (6133B)
1 #!/usr/bin/env python 2 # 3 # Copyright 2013 Google Inc. All Rights Reserved. 4 # 5 # Redistribution and use in source and binary forms, with or without 6 # modification, are permitted provided that the following conditions are 7 # met: 8 # 9 # * Redistributions of source code must retain the above copyright 10 # notice, this list of conditions and the following disclaimer. 11 # * Redistributions in binary form must reproduce the above 12 # copyright notice, this list of conditions and the following disclaimer 13 # in the documentation and/or other materials provided with the 14 # distribution. 15 # * Neither the name of Google Inc. nor the names of its 16 # contributors may be used to endorse or promote products derived from 17 # this software without specific prior written permission. 18 # 19 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31 """Script for branching Google Test/Mock wiki pages for a new version. 32 33 SYNOPSIS 34 release_docs.py NEW_RELEASE_VERSION 35 36 Google Test and Google Mock's external user documentation is in 37 interlinked wiki files. When we release a new version of 38 Google Test or Google Mock, we need to branch the wiki files 39 such that users of a specific version of Google Test/Mock can 40 look up documentation relevant for that version. This script 41 automates that process by: 42 43 - branching the current wiki pages (which document the 44 behavior of the SVN trunk head) to pages for the specified 45 version (e.g. branching FAQ.wiki to V2_6_FAQ.wiki when 46 NEW_RELEASE_VERSION is 2.6); 47 - updating the links in the branched files to point to the branched 48 version (e.g. a link in V2_6_FAQ.wiki that pointed to 49 Primer.wiki#Anchor will now point to V2_6_Primer.wiki#Anchor). 50 51 NOTE: NEW_RELEASE_VERSION must be a NEW version number for 52 which the wiki pages don't yet exist; otherwise you'll get SVN 53 errors like "svn: Path 'V1_7_PumpManual.wiki' is not a 54 directory" when running the script. 55 56 EXAMPLE 57 $ cd PATH/TO/GTEST_SVN_WORKSPACE/trunk 58 $ scripts/release_docs.py 2.6 # create wiki pages for v2.6 59 $ svn status # verify the file list 60 $ svn diff # verify the file contents 61 $ svn commit -m "release wiki pages for v2.6" 62 """ 63 64 __author__ = 'wan@google.com (Zhanyong Wan)' 65 66 import os 67 import re 68 import sys 69 70 import common 71 72 73 # Wiki pages that shouldn't be branched for every gtest/gmock release. 74 GTEST_UNVERSIONED_WIKIS = ['DevGuide.wiki'] 75 GMOCK_UNVERSIONED_WIKIS = [ 76 'DesignDoc.wiki', 77 'DevGuide.wiki', 78 'KnownIssues.wiki' 79 ] 80 81 82 def DropWikiSuffix(wiki_filename): 83 """Removes the .wiki suffix (if any) from the given filename.""" 84 85 return (wiki_filename[:-len('.wiki')] if wiki_filename.endswith('.wiki') 86 else wiki_filename) 87 88 89 class WikiBrancher(object): 90 """Branches ...""" 91 92 def __init__(self, dot_version): 93 self.project, svn_root_path = common.GetSvnInfo() 94 if self.project not in ('googletest', 'googlemock'): 95 sys.exit('This script must be run in a gtest or gmock SVN workspace.') 96 self.wiki_dir = svn_root_path + '/wiki' 97 # Turn '2.6' to 'V2_6_'. 98 self.version_prefix = 'V' + dot_version.replace('.', '_') + '_' 99 self.files_to_branch = self.GetFilesToBranch() 100 page_names = [DropWikiSuffix(f) for f in self.files_to_branch] 101 # A link to Foo.wiki is in one of the following forms: 102 # [Foo words] 103 # [Foo#Anchor words] 104 # [http://code.google.com/.../wiki/Foo words] 105 # [http://code.google.com/.../wiki/Foo#Anchor words] 106 # We want to replace 'Foo' with 'V2_6_Foo' in the above cases. 107 self.search_for_re = re.compile( 108 # This regex matches either 109 # [Foo 110 # or 111 # /wiki/Foo 112 # followed by a space or a #, where Foo is the name of an 113 # unversioned wiki page. 114 r'(\[|/wiki/)(%s)([ #])' % '|'.join(page_names)) 115 self.replace_with = r'\1%s\2\3' % (self.version_prefix,) 116 117 def GetFilesToBranch(self): 118 """Returns a list of .wiki file names that need to be branched.""" 119 120 unversioned_wikis = (GTEST_UNVERSIONED_WIKIS if self.project == 'googletest' 121 else GMOCK_UNVERSIONED_WIKIS) 122 return [f for f in os.listdir(self.wiki_dir) 123 if (f.endswith('.wiki') and 124 not re.match(r'^V\d', f) and # Excluded versioned .wiki files. 125 f not in unversioned_wikis)] 126 127 def BranchFiles(self): 128 """Branches the .wiki files needed to be branched.""" 129 130 print 'Branching %d .wiki files:' % (len(self.files_to_branch),) 131 os.chdir(self.wiki_dir) 132 for f in self.files_to_branch: 133 command = 'svn cp %s %s%s' % (f, self.version_prefix, f) 134 print command 135 os.system(command) 136 137 def UpdateLinksInBranchedFiles(self): 138 139 for f in self.files_to_branch: 140 source_file = os.path.join(self.wiki_dir, f) 141 versioned_file = os.path.join(self.wiki_dir, self.version_prefix + f) 142 print 'Updating links in %s.' % (versioned_file,) 143 text = file(source_file, 'r').read() 144 new_text = self.search_for_re.sub(self.replace_with, text) 145 file(versioned_file, 'w').write(new_text) 146 147 148 def main(): 149 if len(sys.argv) != 2: 150 sys.exit(__doc__) 151 152 brancher = WikiBrancher(sys.argv[1]) 153 brancher.BranchFiles() 154 brancher.UpdateLinksInBranchedFiles() 155 156 157 if __name__ == '__main__': 158 main()