rst2db-opf 1.1.6

先决条件

在安装rst2db opf之前，您需要以下先决条件：

• libxml2和头（libxml2和libxml2 dev）
• libxml2的python绑定（python lxml或python3 lxml）
• libxslt1头（libxslt1 dev）
• python头（python dev或python3 dev）

您可以通过运行：

sudo apt-get install libxml2 libxml2-dev libxslt1-dev

以及one的以下选项，具体取决于您的Python版本：

sudo apt-get install python3-lxml python3-dev

sudo apt-get install python-lxml python-dev

为OpenPower项目使用Sphinx扩展

这个包用于帮助OpenPOWER Foundation项目使用基于RST的文档 （例如SkiBoot）将他们的文档转换为OpenPOWER Foundation的外观这个 通过扩展常用的sphinx构建环境来实现，以构建opf类型 PDF和HTML产品。这是在构建过程中通过转换RST来实现的 文件到XML（DocBook）并以编程方式与OpenPower Foundation合并 基于maven的文档构建。

完成此操作的步骤如下：

1. 通过运行：

   sudo -H pip install rst2db-opf
   

2. 更新conf.py文件中的sphinx-build扩展名以包括 这一行如下：

   extensions = [
      ... other extensions here ... ,
      openpowerfoundation.sphinx_ext.docbook_builder
      ]
   

3. 还将以下行添加到conf.py文件中，以增强 sphinx-build环境：

   # -- Options for Docbook output -------------------------------------------
   docbook_default_root_element = 'section'
   docbook_standalone = 'False'
   
   # -- Settings for OpenPOWER Foundation Docbook output ---------------------
   # The following structure defines which files and tags in the OpenPOWER
   # Foundation Docs-Template/rst_template directory get updated.  The
   # opf_docbook.py file imports conf.py (this file) and uses the
   # opf_docbook_settings structure to replace tags in the respected files.
   #
   # The structure of the following hash is:
   #
   #   { file_name : { tag_name : tag_value, ... }, ... }
   #
   # The GitHub project containing the template and the tool can be
   # located at https://github.com/OpenPOWERFoundation/Docs-Template
   #
   opf_docbook_settings = {
       u'pom.xml' :    { u'artifactId' : u'<TBD>',
                         u'name' : u'<TBD>',
                         u'disqusShortname' : u'<TBD>',
                         u'webhelpDirname' : u'<TBD>',
                         u'pdfFilenameBase' : u'<TBD>',
                         u'workProduct' : u'<TBD: workgroupNotes, workgroupSpecification, candidateStandard, or openpowerStandard>',
                         u'security' : u'<TBD: public, workgroupConfidential, or foundationConfidential>',
                         u'documentStatus' : u'<TBD: draft, review, or published>' },
   
       u'bk_main.xml': { u'title' : u'<TBD>',
                         u'subtitle' : u'<TBD>',
                         u'personname' : u'<TBD>',
                         u'email' : u'<TBD>',
                         u'year' : u'<TBD>',
                         u'holder' : u'<TBD>',
                         u'releaseinfo' : u'<TBD>',
                         u'abstract' : u'<TBD>' }
       }
   

   请替换标记为“<；tbd…>；”的opf_docbook_settings中的值 对项目有适当的价值。样品溶液可以在 SkiBoot_doc_conf.pygithub中的文件。有关每个字段的详细信息可以 在OpenPOWER_Foundation_Document_Development_Guide中找到

4. 使用以下更新增强sphinx-buildMakefile。

   • 文件顶部附近需要的常规环境设置：

     # Variables for OPF Docbook conversion
     RMDIR         = rm -rf
     DBEXT         = rst2db-opf
     GIT           = git
     CP            = cp
     MAVEN         = mvn
     OPFMASTER     = https://github.com/OpenPOWERFoundation/Docs-Master.git
     OPFTEMPLATE   = https://github.com/OpenPOWERFoundation/Docs-Template.git
     DBDIR         = $(BUILDDIR)/docbook
     MASTERDIR     = $(BUILDDIR)/Docs-Master
     TEMPLATEDIR   = $(BUILDDIR)/Docs-Template
     OPFBLDDIR     = $(TEMPLATEDIR)/rst_template
     OPFDOCDIR     = $(OPFBLDDIR)/target/docbkx/webhelp
     OPFDBDIR      = $(DBDIR)/opf_docbook
     PROCXML       = opf_docbook.py
     

   • 一组用于生成新make目标的命令，docbook。复制以下内容 在Makefile底部的行保持不变：

     docbook:
       # User-friendly check for docbook extension (opf_rst2db)
       ifeq ($(shell which $(DBEXT) >/dev/null 2>&1; echo $$?), 1)
       $(error The '$(DBEXT)' command was not found. Make sure you have Sphinx extension rst2db-opf installed. Grab it from https://pypi.python.org/pypi/rst2db-opf or pip install rst2db-opf.)
       endif
     
       # User-friend check for git
       ifeq ($(shell which $(GIT) >/dev/null 2>&1; echo $$?), 1)
       $(error The '$(GIT)' command was not found. Make sure you have git installed.
       endif
     
       $(RMDIR) $(DBDIR)/doctrees/
       $(SPHINXBUILD) -v -b docbook $(ALLSPHINXOPTS) $(DBDIR)
       $(RMDIR) $(DBDIR)/doctrees/
       @echo
       @echo "Build finished. The XML files are in $(DBDIR)."
       @echo "Cloning OpenPOWER Docbook template information"
       if [ -d $(MASTERDIR) ]; then $(RMDIR) $(MASTERDIR);    fi;
       $(GIT) clone $(OPFMASTER) $(MASTERDIR)
       if [ -d $(TEMPLATEDIR) ];  then $(RMDIR) $(TEMPLATEDIR); fi;
       $(GIT) clone $(OPFTEMPLATE) $(TEMPLATEDIR)
       @echo "Retrieving conversion program from $(OPFBLDDIR)"
       $(CP) $(OPFBLDDIR)/$(PROCXML) .
       @echo "Starting conversion code"
       python $(PROCXML) -b $(BUILDDIR) -d $(DBDIR) -m $(MASTERDIR) -t $(TEMPLATEDIR)
       @echo
       @echo "Conversion done, building OPF documents"
       cd $(OPFBLDDIR); \
       $(MAVEN) generate-sources
       if [ -d $(OPFDOCDIR) ]; then cp -a $(OPFDOCDIR)/ $(OPFDBDIR); fi;
       @echo
       @echo "If build was successful, PDF and HTML will be found in $(OPFDBDIR)
     

   可能需要进行其他更新，例如（help:target）中的命令帮助文本。 有关工作的Makefile示例，请参阅github中的SkiBoot_doc_Makefile。

有关上述设置或转换过程的详细信息 一般来说，请参考OpenPOWER_Foundation_Document_Development_Guide。

附加工具文档

以下部分是为一般工具使用而提供的，但不是openpower所必需的 基础文档支持。

rst2db-opf <filename> [-e root_element] [-o output_file] [-t template_file]

<?xml version="1.0" encoding="utf-8"?><!DOCTYPE {{data.root_element}} PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"><{{data.root_element}}>
    {{data.contents}}
</{{data.root_element}}>

extensions = [
   ... other extensions here ... ,
   openpowerfoundation.sphinx_ext.docbook_builder
   ]

docbook_template_file='dbtemplate.xml'docbook_default_root_element=chapter

sphinx-build source output -b docbook

许可证

此软件是在BSD 3-Clause许可证下提供的。见 LICENSE文件了解更多详细信息。

有关详细信息

联系人：openpower系统软件工作组主席<；syssw-chair@openpowerfoundation.org>；