Home | History | Annotate | Download | only in scripts
      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 documenation 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 (at] 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()
    159