X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=build.py;h=dbe5448e56bdf85a8b9c42ddd07a9a3e586e59ec;hb=1bc084d882bf5792634c5fd08c35eff78de26b02;hp=8ac84d4efb4e93859685ad7fb7f0962ebad7de26;hpb=178bba3b522fbe071ac0c5bc3d48c40b4e41476b;p=ardour-manual diff --git a/build.py b/build.py index 8ac84d4..dbe5448 100755 --- a/build.py +++ b/build.py @@ -9,7 +9,7 @@ # Remnants (could go into the master document as the first header) -#bootstrap_path: /bootstrap-2.2.2 +#bootstrap_path: /bootstrap-3.3.7 #page_title: The Ardour Manual import os @@ -18,15 +18,26 @@ import shutil import argparse +# Global vars +# This matches all *non* letter/number, ' ', '.', '-', and '_' chars +cleanString = re.compile(r'[^a-zA-Z0-9 \._-]+') +# This matches new 'unbreakable' links, up to the closing quote or anchor +findLinks = re.compile(r'"@@[^#"]*[#"]') +githuburl = 'https://github.com/Ardour/manual/edit/master/include/' + # # Create an all lowercase filename without special characters and with spaces # replaced with dashes. # def MakeFilename(s): - # Cleans up the file name, removing all non ASCII or .-_ chars - fn = re.sub(r'[^.\-_a-zA-Z0-9 ]', '', s) - fn = fn.lower() - fn = fn.replace(' ', '-') + global cleanString + # Clean up the file name, removing all non letter/number or " .-_" chars. + # Also, convert to lower case and replace all spaces with dashes. + fn = cleanString.sub('', s).lower().replace(' ', '-') + # Double dashes can creep in from the above replacement, so we check for + # that here. + fn = fn.replace('--', '-') + return fn @@ -112,12 +123,19 @@ def GetFileStructure(): level = PartToLevel(hdr['part']) hdr['level'] = level fnames[level] = MakeFilename(hdr['title']) - fullName = '' - for i in range(level + 1): - fullName = fullName + fnames[i] + '/' + # Ickyness--user specified URIs + if 'uri' in hdr: + hdr['filename'] = hdr['uri'] + else: + fullName = '' + + for i in range(level + 1): + fullName = fullName + fnames[i] + '/' + + # Strip trailing '/' on filename + hdr['filename'] = fullName[:-1] - hdr['filename'] = fullName.rstrip('/') fs.append(hdr) if ('include' not in hdr) and (level > 0): @@ -172,6 +190,36 @@ def GetChildren(fs, pos): return children +# +# Get the parent at this level +# +def GetParent(fs, pos): + thisLevel = fs[pos]['level'] + pos = pos - 1 + + while pos >= 0 and fs[pos]['level'] >= thisLevel: + pos = pos - 1 + + return pos + + +# +# Creates the BreadCrumbs +# +def GetBreadCrumbs(fs, pos): + # The > is for Bootstrap pre-3.0 + breadcrumbs = '
  • '+ fs[pos]['title'] + '
    • ' + + while pos >= 0: + pos = GetParent(fs, pos) + + if pos >= 0: + breadcrumbs='
  • '+ fs[pos]['title'] + '
    • '+ breadcrumbs + + breadcrumbs = '' + return breadcrumbs + + # # Make an array of children attached to each node in the file structure # (It's a quasi-tree structure, and can be traversed as such.) @@ -209,36 +257,54 @@ def FindInternalLinks(fs): for hdr in fs: if 'link' in hdr: - linkDict['@@' + hdr['link']] = '/' + hdr['filename'] + '/' + linkDict['"@@' + hdr['link'] + '"'] = '"/' + hdr['filename'] + '/"' + linkDict['"@@' + hdr['link'] + '#'] = '"/' + hdr['filename'] + '/index.html#' + + + return linkDict + +# +# Same as above, but create anchors (for the one-page version) +# +def FindInternalAnchors(fs): + linkDict = {} + + for hdr in fs: + if 'link' in hdr: + linkDict['"@@' + hdr['link'] + '"'] = '"#' + hdr['link'] + '"' + linkDict['"@@' + hdr['link'] + '#'] = '"#' + hdr['link'] + '"' + return linkDict # # Internal links are of the form '@@link-name', which are references to the -# 'link:' field in the part header. We have to find all occurances and replace +# 'link:' field in the part header. We have to find all occurrences and replace # them with the appropriate link. # def FixInternalLinks(links, content, title): - - # Make key1|key2|key3|... out of our links keys - pattern = re.compile('|'.join(links.keys())) - - # Use a lambda callback to substitute each occurance found - result = pattern.sub(lambda x: links[x.group()], content) - - # Check for missing link targets, and report them to the user - match = re.findall('"@@.*"', result) + global findLinks + match = findLinks.findall(content) + missing = [] if len(match) > 0: - print('\nMissing link target' + ('s' if len(match) > 1 else '') + ' in "' + title + '":') - for s in match: - print(' ' + s[3:-1]) + if s in links: + content = content.replace(s, links[s]) + else: + missing.append(s) + + # Report missing link targets to the user (if any) + if len(missing) > 0: + print('\nMissing link target' + ('s' if len(missing) > 1 else '') + ' in "' + title + '":') + + for s in missing: + print(' ' + s) print() - return result + return content # @@ -253,7 +319,8 @@ def BuildList(lst, fs, pagePos, cList): nextPos = lst[i + 1] if i + 1 < len(lst) else len(fs) active = ' class=active' if curPos == pagePos else '' - content = content + '' + fs[curPos]['title'] + '' + menuTitle = fs[curPos]['menu_title'] if 'menu_title' in fs[curPos] else fs[curPos]['title'] + content = content + '' + menuTitle + '' # If the current page is our page, and it has children, enumerate them if curPos == pagePos: @@ -271,43 +338,102 @@ def BuildList(lst, fs, pagePos, cList): return content + +# +# Builds the sidebar for the one-page version +# +def BuildOnePageSidebar(fs): + + content = '\n\n
      \n' + lvl = 0 + levelNums = [0]*6 + + for i in range(len(fs)): + # Handle Part/Chapter/subchapter/section/subsection numbering + level = fs[i]['level'] + if level == 0: + levelNums[2] = 0 + levelNums[3] = 0 + levelNums[4] = 0 + elif level == 1: + levelNums[2] = 0 + levelNums[3] = 0 + levelNums[4] = 0 + elif level == 2: + levelNums[3] = 0 + levelNums[4] = 0 + elif level == 3: + levelNums[4] = 0 + levelNums[level] = levelNums[level] + 1; + j = level + txtlevel = '' + while j > 0: #level 0 is the part number which is not shown + txtlevel = str(levelNums[j]) + '.' + txtlevel + j = j-1 + if len(txtlevel) > 0: + txtlevel = txtlevel[:-1] + ' - ' + + if 'link' in fs[i]: + anchor = fs[i]['link'] + else: + anchor = fs[i]['filename'] + + while lvl < level: + content = content + '
        \n' + lvl = lvl + 1 + while lvl > level: + content = content + '
      \n' + lvl = lvl - 1 + + content = content + '
    • ' + txtlevel + fs[i]['title'] + '
      • \n' + + content = content + '
    \n' + + return content + + # # Create link sidebar given a position in the list. # def CreateLinkSidebar(fs, pos, childList): # Build the list recursively from the top level nodes + #content = BuildList(FindTopLevelNodes(fs), fs, pos, childList) content = BuildList(FindTopLevelNodes(fs), fs, pos, childList) - # Shove the TOC link in the top... - content = content[:7] + '
    Table of Contents
    \n' + content[7:] + # Shove the TOC link and one file link at the top... + content = content[:7] + '
    Table of Contents
    \n' + content[7:] return content - # Preliminaries # We have command line arguments now, so deal with them parser = argparse.ArgumentParser(description='A build script for the Ardour Manual') parser.add_argument('-v', '--verbose', action='store_true', help='Display the high-level structure of the manual') parser.add_argument('-q', '--quiet', action='store_true', help='Suppress all output (overrides -v)') +parser.add_argument('-d', '--devmode', action='store_true', help='Add content to pages to help developers debug them') args = parser.parse_args() verbose = args.verbose quiet = args.quiet +devmode = args.devmode if quiet: verbose = False -#verbose = False level = 0 fileCount = 0 levelNums = [0]*6 lastFile = '' page = '' +onepage = '' toc = '' pageNumber = 0 siteDir = './website/' +if not quiet and devmode: + print('Devmode active: scribbling extra junk to the manual...') + if os.access(siteDir, os.F_OK): if not quiet: print('Removing stale HTML data...') @@ -316,20 +442,22 @@ if os.access(siteDir, os.F_OK): shutil.copytree('./source', siteDir) -# Yeah, need to make a symlink in include/ too :-P -# [this will go away when the rewrite happens] -if (os.access('include/_manual', os.F_OK) == False): - os.symlink('../_manual/', 'include/_manual') - # Read the template, and fix the stuff that's fixed for all pages temp = open('page-template.txt') template = temp.read() temp.close() -template = template.replace('{{page.bootstrap_path}}', '/bootstrap-2.2.2') +template = template.replace('{{page.bootstrap_path}}', '/bootstrap-3.3.7') template = template.replace('{{page.page_title}}', 'The Ardour Manual') +# Same as above, but for the One-page version +temp = open('onepage-template.txt') +onepage = temp.read() +temp.close() + +onepage = onepage.replace('{{page.bootstrap_path}}', '/bootstrap-3.3.7') +onepage = onepage.replace('{{page.page_title}}', 'The Ardour Manual') # Parse out the master docuemnt's structure into a dictionary list fileStruct = GetFileStructure() @@ -339,6 +467,7 @@ nodeChildren = FindChildren(fileStruct) # Create a dictionary for translation of internal links to real links links = FindInternalLinks(fileStruct) +oplinks = FindInternalAnchors(fileStruct) if not quiet: print('Found ' + str(len(links)) + ' internal link target', end='') @@ -369,10 +498,15 @@ for header in fileStruct: # Handle Part/Chapter/subchapter/section/subsection numbering if level == 0: levelNums[2] = 0 + levelNums[3] = 0 + levelNums[4] = 0 elif level == 1: levelNums[2] = 0 + levelNums[3] = 0 + levelNums[4] = 0 elif level == 2: levelNums[3] = 0 + levelNums[4] = 0 elif level == 3: levelNums[4] = 0 @@ -391,17 +525,32 @@ for header in fileStruct: print(header['title']) - # Handle TOC scriblings... + # Handle TOC scriblings and one-page titles... + opl = '' + + if 'link' in header: + opl = ' id="' + header['link'] + '"' + else: + opl = ' id="' + header['filename'] + '"' + if level == 0: toc = toc + '

    Part ' + num2roman(levelNums[level]) + ': ' + header['title'] + '

    \n'; + oph = '

    Part ' + num2roman(levelNums[level]) + ' - ' + header['title'] + '

    \n'; elif level == 1: - toc = toc + '

    Ch. ' + str(levelNums[level]) + ':  ' + header['title'] + '

    \n' + toc = toc + '\t

    Ch. ' + str(levelNums[level]) + ':  ' + header['title'] + '

    \n' + oph = '

    ' + str(levelNums[level]) + ' - ' + header['title'] + '

    \n'; elif level == 2: - toc = toc + ' ' + header['title'] + '
    \n' + toc = toc + '\t\t

    ' + header['title'] + '

    \n' + oph = '

    ' + str(levelNums[level-1]) + '.' + str(levelNums[level]) + ' - ' + header['title'] + '

    \n'; elif level == 3: - toc = toc + ' ' + header['title'] + '
    \n' + toc = toc + '\t\t\t

    ' + header['title'] + '

    \n' + oph = '

    ' + str(levelNums[level-2]) + '.' + str(levelNums[level-1]) + '.' + str(levelNums[level]) + ' - ' + header['title'] + '

    \n'; elif level == 4: - toc = toc + ' ' + header['title'] + '
    \n' + toc = toc + '\t\t\t\t

    ' + header['title'] + '

    \n' + oph = '

    ' + str(levelNums[level-3]) + '.' + str(levelNums[level-2]) + '.' + str(levelNums[level-1]) + '.' + str(levelNums[level]) + ' - ' + header['title'] + '

    \n'; + + + # Make the 'this thing contains...' stuff if HaveChildren(fileStruct, pageNumber): @@ -412,17 +561,28 @@ for header in fileStruct: more = '
    \n' + '

    This section contains the following topics:

    \n' + '
      \n' + more + '
    \n' + '
    \n' - # Make the 'Previous' & 'Next' content + parent = GetParent(fileStruct, pageNumber) + + # Make the 'Previous', 'Up' & 'Next' content nLink = '' pLink = '' + uLink = '' if pageNumber > 0: - pLink = '
    • ' + pLink = '' if pageNumber < len(fileStruct) - 1: - nLink = '
    • ' + nLink = '' - prevnext = '
      ' + pLink + nLink + '
    ' + if level > 0: + uLink = '
  • ↑ Up
    • ' + else: + uLink = '
  • ↑ Up
    • ' + + prevnext = '
      ' + pLink + uLink + nLink + '
    ' + + # Make the BreadCrumbs + breadcrumbs = GetBreadCrumbs(fileStruct, pageNumber) # Create the link sidebar sidebar = CreateLinkSidebar(fileStruct, pageNumber, nodeChildren) @@ -431,9 +591,11 @@ for header in fileStruct: # Chapters, subchapters, sections & subsections can all have content, # but the basic fundamental organizing unit WRT content is still the # chapter. + githubedit = '' if level > 0: if 'include' in header: srcFile = open('include/' + header['include']) + githubedit = 'Edit on GitHub' content = srcFile.read() srcFile.close() @@ -449,6 +611,31 @@ for header in fileStruct: else: content = '[something went wrong]' + # Add header information to the page if in dev mode + if devmode: + devnote ='' + content + + # ----- One page version ----- + + # Fix up any internal links + opcontent = FixInternalLinks(oplinks, content, header['title']) + + # Create the link sidebar + opsidebar = BuildOnePageSidebar(fileStruct) + + # Set up the actual page from the template + onepage = onepage.replace('{% tree %}', opsidebar) + onepage = onepage.replace('{{ content }}', oph + '\n' + opcontent + '{{ content }}') + + # ----- Normal version ----- + # Fix up any internal links content = FixInternalLinks(links, content, header['title']) @@ -463,10 +650,13 @@ for header in fileStruct: page = page.replace('{{ page.title }}', header['title']) page = page.replace('{% tree %}', sidebar) page = page.replace('{% prevnext %}', prevnext) + page = page.replace('{% githubedit %}', githubedit) + page = page.replace('{% breadcrumbs %}', breadcrumbs) page = page.replace('{{ content }}', content + more) - # Create the directory for the index.html file to go into - os.mkdir(siteDir + header['filename'], 0o775) + # Create the directory for the index.html file to go into (we use makedirs, + # because we have to in order to accomodate the 'uri' keyword) + os.makedirs(siteDir + header['filename'], 0o775, exist_ok=True) # Finally, write the file! destFile = open(siteDir + header['filename'] + '/index.html', 'w') @@ -485,11 +675,20 @@ page = page.replace('{{ page.title }}', 'Ardour Table of Contents') page = page.replace('{% tree %}', sidebar) page = page.replace('{{ content }}', toc) page = page.replace('{% prevnext %}', '') +page = page.replace('{% githubedit %}', '') +page = page.replace('{% breadcrumbs %}', '') os.mkdir(siteDir + 'toc', 0o775) tocFile = open(siteDir + 'toc/index.html', 'w') tocFile.write(page) tocFile.close() +# Create the one-page version of the documentation +onepageFile = open(siteDir + 'ardourmanual.html', 'w') +onepage = onepage.replace('{{ content }}', '') # cleans up the last spaceholder +onepageFile.write(onepage) +onepageFile.close() + + if not quiet: print('Processed ' + str(fileCount) + ' files.')