1#!/usr/bin/env python 2# Copyright 2018 The Bazel Authors. All rights reserved. 3# 4# Licensed under the Apache License, Version 2.0 (the "License"); 5# you may not use this file except in compliance with the License. 6# You may obtain a copy of the License at 7# 8# http://www.apache.org/licenses/LICENSE-2.0 9# 10# Unless required by applicable law or agreed to in writing, software 11# distributed under the License is distributed on an "AS IS" BASIS, 12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13# See the License for the specific language governing permissions and 14# limitations under the License. 15 16""" 17This script should be run without any arguments to update the tests 18documentation cross linking. 19 20It updates sections bounded by 21.. Child list start 22.. Child list end 23 24With links to all the child documentation, picking the text for each item 25from the firts non blank line of the README.rst for that folder. 26""" 27 28import os 29 30README = "README.rst" 31START_MARKER = ".. Child list start\n" 32END_MARKER = ".. Child list end\n" 33 34def main(): 35 for dirname, subdirs, files in os.walk("."): 36 if README not in files: 37 continue 38 readme = os.path.join(dirname, README) 39 out = [] 40 lines = [] 41 with open(readme) as f: 42 lines = f.readlines() 43 try: 44 start = lines.index(START_MARKER) 45 end = lines.index(END_MARKER) 46 except ValueError: 47 print('{}: No child markers'.format(readme)) 48 continue 49 if end < start: 50 print('{}: Invalid child markers'.format(readme)) 51 continue 52 print('{}: updating from {} to {}'.format(readme, start, end)) 53 out = lines[:start+1] 54 out.append("\n") 55 for sub in subdirs: 56 child = os.path.join(dirname, sub, README) 57 try: 58 with open(child) as f: 59 for line in f.readlines(): 60 childname = line.strip() 61 if childname: 62 break 63 if childname: 64 out.append("* `{} <{}/{}>`_\n".format(childname, sub, README)) 65 except: 66 continue 67 out.append("\n") 68 out.extend(lines[end:]) 69 if out: 70 with open(readme, "w") as f: 71 f.writelines(out) 72 73 74if __name__ == "__main__": 75 main()