Add preliminary director rst_template for rst support
Signed-off-by: Jeff Scheel <scheel@us.ibm.com>master
Jeff Scheel
8 years ago
parent
95a8d02310
commit
c022c95f88
@ -0,0 +1,89 @@
|
|||||||
|
<?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.
|
||||||
|
|
||||||
|
-->
|
||||||
|
|
||||||
|
<!-- The following entity variable is used to reflect the version of the
|
||||||
|
template document master used for building a document. This value
|
||||||
|
should be set by copy of the of template used to create a new
|
||||||
|
document and should not be changed. Use of this value is in
|
||||||
|
in the Abstract section in this file. -->
|
||||||
|
<!DOCTYPE book [
|
||||||
|
<!ENTITY template_version "1.1.0">
|
||||||
|
]>
|
||||||
|
|
||||||
|
<book xmlns="http://docbook.org/ns/docbook"
|
||||||
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
|
version="5.0"
|
||||||
|
xml:id="bk_main">
|
||||||
|
|
||||||
|
<!-- All TBD values are assumed by the XXX.py package to be contained in the conf.py
|
||||||
|
opf_docbook_documents[] hash by tag name -->
|
||||||
|
<title>TBD</title>
|
||||||
|
<subtitle>TBD</subtitle>
|
||||||
|
|
||||||
|
<info>
|
||||||
|
<author>
|
||||||
|
<personname>TBD</personname>
|
||||||
|
<email>TBD</email>
|
||||||
|
<affiliation>
|
||||||
|
<orgname>OpenPower Foundation</orgname>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
<copyright>
|
||||||
|
<year>TBD</year>
|
||||||
|
<holder>TBD</holder>
|
||||||
|
</copyright>
|
||||||
|
<releaseinfo>TBD</releaseinfo>
|
||||||
|
<productname>OpenPOWER</productname>
|
||||||
|
<pubdate/>
|
||||||
|
|
||||||
|
<!-- TODO: Select one of the two following legalnotice role= values:
|
||||||
|
"apache2" for an Apache V2 license or
|
||||||
|
"opfExternal" for an official OpenPOWER Foundation external license text.
|
||||||
|
If you don't know which one to select, change to "opfExternal" and ask your TSC representative. -->
|
||||||
|
<legalnotice role="apache2">
|
||||||
|
<!--legalnotice role="opfExternal"-->
|
||||||
|
|
||||||
|
<annotation>
|
||||||
|
<remark>Copyright details are filled in by the template.</remark>
|
||||||
|
</annotation>
|
||||||
|
</legalnotice>
|
||||||
|
|
||||||
|
<abstract>TBD</abstract>
|
||||||
|
|
||||||
|
<revhistory>
|
||||||
|
<!-- TODO: Set the initial version information and clear any old information out -->
|
||||||
|
<revision>
|
||||||
|
<date>2017-02-17</date>
|
||||||
|
<revdescription>
|
||||||
|
<para>TBD</para>
|
||||||
|
</revdescription>
|
||||||
|
</revision>
|
||||||
|
</revhistory>
|
||||||
|
</info>
|
||||||
|
|
||||||
|
<!-- The ch_preface.xml file is required by all documents -->
|
||||||
|
<xi:include href="../../Docs-Master/common/ch_preface.xml"/>
|
||||||
|
|
||||||
|
<!-- Do not change the following statement as it's expected by the opf_docbook.py tool which copies the RST TOC file contents in here -->
|
||||||
|
<!--TBD-->
|
||||||
|
|
||||||
|
<!-- The app_foundation.xml appendix file is required by all documents. -->
|
||||||
|
<xi:include href="../../Docs-Master/common/app_foundation.xml"/>
|
||||||
|
|
||||||
|
</book>
|
||||||
@ -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 <section> 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 <chapter>
|
||||||
|
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 <chapter>
|
||||||
|
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 <section>'
|
||||||
|
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 '<book' not in line and '</book>' 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 = '<!--TBD-->'
|
||||||
|
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 <builddir> -d <docbookdir> -m <masterdir> -t <templatedir>'
|
||||||
|
sys.exit(-1)
|
||||||
|
for opt, arg in opts:
|
||||||
|
if opt == '-h':
|
||||||
|
print 'opf_docbook.py -b <builddir> -d <docbookdir> -m <masterdir> -t <templatedir>'
|
||||||
|
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+'</'+tag+'>'
|
||||||
|
else:
|
||||||
|
new_str = ''
|
||||||
|
|
||||||
|
old_str = '<'+tag+'>TBD</'+tag+'>'
|
||||||
|
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 <book> and <title> 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:])
|
||||||
@ -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>
|
||||||
Loading…
Reference in New Issue