From c022c95f88bd882e66dba6204db2baf2f57a4939 Mon Sep 17 00:00:00 2001 From: Jeff Scheel Date: Fri, 21 Apr 2017 13:31:17 -0500 Subject: [PATCH] Add preliminary director rst_template for rst support Signed-off-by: Jeff Scheel --- rst_template/bk_main.xml | 89 +++++++++++++++ rst_template/opf_docbook.py | 209 ++++++++++++++++++++++++++++++++++++ rst_template/pom.xml | 162 ++++++++++++++++++++++++++++ 3 files changed, 460 insertions(+) create mode 100644 rst_template/bk_main.xml create mode 100644 rst_template/opf_docbook.py create mode 100644 rst_template/pom.xml diff --git a/rst_template/bk_main.xml b/rst_template/bk_main.xml new file mode 100644 index 0000000..7419b39 --- /dev/null +++ b/rst_template/bk_main.xml @@ -0,0 +1,89 @@ + + + + + +]> + + + + + TBD + TBD + + + + TBD + TBD + + OpenPower Foundation + + + + TBD + TBD + + TBD + OpenPOWER + + + + + + + + Copyright details are filled in by the template. + + + + TBD + + + + + 2017-02-17 + + TBD + + + + + + + + + + + + + + + diff --git a/rst_template/opf_docbook.py b/rst_template/opf_docbook.py new file mode 100644 index 0000000..f89a70d --- /dev/null +++ b/rst_template/opf_docbook.py @@ -0,0 +1,209 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- +# +# Builds OpenPOWER Foundation documentation using standard template. +# +# Assumes rst2db has been used to convert rst to docbook. +# +import os, sys, getopt, shutil, errno +from lxml import etree +from conf import opf_docbook_settings, master_doc + +def copy_xml_to_template(src_dir, tgt_dir): + # Copy XML files + src_files = os.listdir(src_dir) + for filename in src_files: + full_file = os.path.join (src_dir, filename) + if (os.path.isfile(full_file)): + shutil.copy(full_file, tgt_dir) + elif (os.path.isdir(full_file)): + try: + os.makedirs(os.path.join(tgt_dir,filename)) + except OSError as exception: + if exception.errno != errno.EEXIST: + raise + copy_xml_to_template( os.path.join(src_dir,filename), os.path.join(tgt_dir,filename) ) + +def update_file(filename, old_str, new_str): + # Verify tag exists + with open(filename) as f: + s = f.read() + if old_str not in s: + print 'Error: "{old_str}" not found in {filename}.'.format(**locals()) + sys.exit(-2) + + # Safely write the changed content, if found in the file + with open(filename, 'w') as f: + s = s.replace(old_str, new_str) + f.write(s) + +def print_tree(element, level): + # Print current element + num_children = element.__len__() + indent = ' '.ljust(level+1) + print indent, 'Tag: ', element.tag, ' Attrib: ', element.attrib, ' Num children: ', num_children + + for i in range(num_children): + child = element.__getitem__(i) + print_tree(child, level+1) + +def convert_top_level_sections(head, file): + path = os.path.dirname(file) + if 'sect' in head.tag: + head.tag = 'book' + + # Clear attributes + for attrib in head.attrib.keys(): + head.attrib.pop(attrib, None) + if head.attrib.items() != []: + print 'Error: Section attributes not removed. ', head.attrib.items(), ' items remain -- ', head.attrib.keys() + sys.exit(-5) + + # Walk children to remove title + num_children = head.__len__() + for i in range(num_children): + child = head.__getitem__(i) + if 'title' in child.tag: + head.__delitem__(i) + break + + # Walk children looking for next set of
tags, opening include files if necessary + num_children = head.__len__() + num_chapter = 0 + for i in range(num_children): + child = head.__getitem__(i) + + # check for section tag + if 'section' in child.tag: + # Convert tag to + child.tag = child.tag.replace('section','chapter') + num_chapter = num_chapter+1 + + # check for include tag + if 'include' in child.tag: + # Open and parse include file + # NOTE: We will only check one level deep + include_file = child.attrib['href'] + full_include_file = os.path.join(path,include_file) + parser = etree.XMLParser(remove_comments=False) + tree = etree.parse(full_include_file, parser=parser) + #print_tree( tree.getroot(), 0 ) + + # Check for sections + include_head = tree.getroot() + if 'sect' in include_head.tag: + # Convert tag to + include_head.tag = include_head.tag.replace('section','chapter') + num_chapter = num_chapter+1 + + # Create backup file + shutil.copy2(full_include_file, full_include_file+'.bak') + + # Write out changed file + tree.write(full_include_file) + if num_chapter == 0: + print 'Error: No chapters found in document' + sys.exit(-6) + else: + print 'Toc file contains ', head.tag, 'tag, not
' + sys.exit(-4) + +def remove_book_tags(old_file, new_file): + with open(old_file, 'r') as input: + with open(new_file, 'wb') as output: + for line in input: + if '' not in line: + output.write(line) + +def insert_toc_into_book(toc_file, book_file): + book_file_bak = book_file+'.bak' + shutil.copy2(book_file, book_file_bak) + key_string = '' + inserted_toc = False + + with open(book_file_bak, 'r') as input: + with open(book_file, 'wb') as output: + for line in input: + if key_string not in line: + output.write(line) + else: + inserted_toc = True + # Write toc_file contents + with open(toc_file, 'r') as input_toc: + for line_toc in input_toc: + output.write(line_toc) + + if not inserted_toc: + print 'Error: key string of "', key_string, '" not found in ', book_file + sys.exit(-7) + +def main(argv): + build_dir = '' + db_dir = '' + master_dir = '' + template_dir = '' + toc_file = master_doc+'.xml' + + try: + opts, args = getopt.getopt(argv,"hb:d:m:t:",["builddir=","docbookdir=","masterdir=","templatedir="]) + except getopt.GetoptError: + print 'Invalid option specified. Usage:' + print ' opf_docbook.py -b -d -m -t ' + sys.exit(-1) + for opt, arg in opts: + if opt == '-h': + print 'opf_docbook.py -b -d -m -t ' + sys.exit() + elif opt in ("-b", "--builddir"): + build_dir = arg + elif opt in ("-d", "--docbookdir"): + db_dir = arg + elif opt in ("-m", "--masterdir"): + master_dir = arg + elif opt in ("-t", "--templatedir"): + template_dir = arg + + # Locate the TOC file + rst_template_dir = os.path.join(template_dir, 'rst_template') + full_toc_file = os.path.join(rst_template_dir, toc_file) + book_file = os.path.join(rst_template_dir, 'bk_main.xml') + + # Copy all files and directories in docbook dir into rst_template recursively + copy_xml_to_template( db_dir, rst_template_dir) + + # Update all file in opf_docbook_settings with tag/value combinations specified + for f in opf_docbook_settings.keys(): + filename = os.path.join(rst_template_dir, f) + tags = opf_docbook_settings[f] + + for tag in tags: + value = opf_docbook_settings[f][tag] + + if value != '': + new_str = '<'+tag+'>'+value+'' + else: + new_str = '' + + old_str = '<'+tag+'>TBD' + update_file(filename, old_str, new_str) + + # Parse TOC file, convert high level tag to "book" and write back out to .tmp1 file + parser = etree.XMLParser(remove_comments=False) + tree = etree.parse(full_toc_file, parser=parser) + # print_tree( tree.getroot(), 0 ) + convert_top_level_sections( tree.getroot(), full_toc_file ) + full_toc_file_tmp1 = full_toc_file+'.tmp1' + tree.write(full_toc_file_tmp1) + + # Eliminate and tags in .tmp1 and write to .tmp2 file + full_toc_file_tmp2 = full_toc_file+'.tmp2' + remove_book_tags(full_toc_file_tmp1, full_toc_file_tmp2) + + # Update link to first file + insert_toc_into_book(full_toc_file_tmp2, book_file) + + sys.exit(0) + + +if __name__ == "__main__": + main(sys.argv[1:]) diff --git a/rst_template/pom.xml b/rst_template/pom.xml new file mode 100644 index 0000000..d54f271 --- /dev/null +++ b/rst_template/pom.xml @@ -0,0 +1,162 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (c) 2016 OpenPOWER Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +--> +<project xmlns="http://maven.apache.org/POM/4.0.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> + + <!-- All TBD values are assumed by the XXX.py package to be contained in the conf.py + opf_docbook_documents[] hash by tag name --> + + <parent> + + <groupId>org.openpowerfoundation.docs</groupId> + <artifactId>workgroup-pom</artifactId> + <version>1.0.0-SNAPSHOT</version> + <relativePath>../pom.xml</relativePath> + </parent> + <modelVersion>4.0.0</modelVersion> + + <artifactId>TBD</artifactId> + + <packaging>jar</packaging> + + <name>TBD</name> + + <properties> + <!-- This is set by Jenkins according to the branch. --> + <release.path.name></release.path.name> + <comments.enabled>0</comments.enabled> + </properties> + <!-- ################################################ --> + <!-- USE "mvn clean generate-sources" to run this POM --> + <!-- ################################################ --> + <build> + <plugins> + <plugin> + + <groupId>org.openpowerfoundation.docs</groupId> + + <artifactId>openpowerdocs-maven-plugin</artifactId> + <!-- version set in ../pom.xml --> + <executions> + <execution> + <id>generate-webhelp</id> + <goals> + <goal>generate-webhelp</goal> + </goals> + <phase>generate-sources</phase> + <configuration> + <!-- These parameters only apply to webhelp --> + <enableDisqus>${comments.enabled}</enableDisqus> + <disqusShortname>TBD</disqusShortname> + <enableGoogleAnalytics>1</enableGoogleAnalytics> + <googleAnalyticsId>UA-17511903-1</googleAnalyticsId> + <generateToc> + appendix toc,title + article/appendix nop + article toc,title + book toc,title,figure,table,example,equation + book/appendix nop + book/chapter nop + chapter toc,title + chapter/section nop + section toc + part toc,title + reference toc,title + set toc,title + </generateToc> + <!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections--> + <sectionAutolabel>1</sectionAutolabel> + <tocSectionDepth>3</tocSectionDepth> + <sectionLabelIncludesComponentLabel>1</sectionLabelIncludesComponentLabel> + + <webhelpDirname>TBD</webhelpDirname> + <pdfFilenameBase>TBD</pdfFilenameBase> + + <!-- TODO: Define the appropriate work product type. These values are defined by the IPR Policy. + Consult with the Work Group Chair or a Technical Steering Committee member if you have + questions about which value to select. + + If no value is provided below, the document will default to "Work Group Notes".--> + <!--workProduct>workgroupNotes</workProduct--> + <!-- workProduct>workgroupSpecification</workProduct --> + <!-- workProduct>candidateStandard</workProduct --> + <!-- workProduct>openpowerStandard</workProduct --> + <workProduct>TBD</workProduct> + + <!-- TODO: Set the appropriate security policy for the document. For documents + which are not "public" this will affect the document title page and + create a vertical running ribbon on the internal margin of the + security status in all CAPS. Values and definitions are formally + defined by the IPR policy. A layman's definition follows: + + public = this document may be shared outside the + foundation and thus this setting must be + used only when completely sure it allowed + foundationConfidential = this document may be shared freely with + OpenPOWER Foundation members but may not be + shared publicly + workgroupConfidential = this document may only be shared within the + work group and should not be shared with + other Foundation members or the public + + The appropriate starting security for a new document is "workgroupConfidential". --> + <!-- security>workgroupConfidential</security --> + <!-- security>foundationConfidential</security --> + <!-- security>public</security--> + <security>TBD</security> + + <!-- TODO: Set the appropriate work flow status for the document. For documents + which are not "published" this will affect the document title page + and create a vertical running ribbon on the internal margin of the + security status in all CAPS. Values and definitions are formally + defined by the IPR policy. A layman's definition follows: + + published = this document has completed all reviews and has + been published + draft = this document is actively being updated and has + not yet been reviewed + review = this document is presently being reviewed + + The appropriate starting security for a new document is "draft". --> + <!-- documentStatus>draft</documentStatus --> + <!-- documentStatus>review</documentStatus --> + <!-- documentStatus>published</documentStatus --> + <documentStatus>TBD</documentStatus> + + </configuration> + </execution> + </executions> + <configuration> + <!-- These parameters apply to pdf and webhelp --> + <xincludeSupported>true</xincludeSupported> + <sourceDirectory>.</sourceDirectory> + <includes> + bk_main.xml + </includes> + + <!-- **TODO: Set to the correct project URL. This likely needs input from the TSC. --> + <!-- canonicalUrlBase>http://openpowerfoundation.org/docs/template-guide/content</canonicalUrlBase --> + <glossaryCollection>${basedir}/../glossary/glossary-terms.xml</glossaryCollection> + <includeCoverLogo>1</includeCoverLogo> + <coverUrl>www.openpowerfoundation.org</coverUrl> + </configuration> + </plugin> + </plugins> + </build> +</project>