googletest/scripts/release_docs.py

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