{ "info": { "author": "OpenPOWER System Software Work Group Chair", "author_email": "syssw-chair@openpowerfoundation.org", "bugtrack_url": null, "classifiers": [], "description": "#############\nrst2db-opf.py\n#############\n\nA reST to DocBook converter (``rst2db-opf``) with an included Sphinx builder\n (openpowerfoundation.spinx_ext.docbook_builder).\n\nThese tools were forked and derived from the rst2db project by Abystrys hosted\nat Abstrys_GitHub_. The OpenPOWER Foundation (OPF) project is now hosted at\nOpenPOWER_Foundation_GitHub_. The python distribution package is available at\nPython_Package_Index_rst2db-opf_Project_.\n\n.. _Abstrys_GitHub: https://github.com/Abstrys/rst2db/\n.. _OpenPOWER_Foundation_GitHub: https://github.com/OpenPOWERFoundation/rst2db-opf/\n.. _Python_Package_Index_rst2db-opf_Project: https://pypi.python.org/pypi/rst2db-opf/\n\nPrerequisites\n=============\n\nBefore installing rst2db-opf, you'll need the following prerequisites:\n\n* libxml2 and headers (**libxml2** and **libxml2-dev**)\n* Python bindings for libxml2 (**python-lxml** or **python3-lxml**)\n* libxslt1 headers (**libxslt1-dev**)\n* Python headers (**python-dev** or **python3-dev**)\n\n**You can install these on Ubuntu / Debian** by running::\n\n sudo apt-get install libxml2 libxml2-dev libxslt1-dev\n\nand *one* of the following, depending on your Python version::\n\n sudo apt-get install python3-lxml python3-dev\n\n sudo apt-get install python-lxml python-dev\n\n\nUsing the sphinx extension for OpenPOWER Projects\n=================================================\n\nThis package is used to assist OpenPOWER Foundation projects with RST-based documentation\n(such as SkiBoot_) convert their documents to the OpenPOWER Foundation look-and-feel. This\nis accomplished by extending the sphinx-build environment commonly used, to build OPF-type\nPDF and html products. This is accomplished during the build by converting the the RST \nfiles to XML (DocBook) and programmatically merging them with OpenPOWER Foundation \nmaven-based document builds.\n\nThe steps to accomplish this are as follows:\n\n1. Install this package from PyPI by running::\n\n sudo -H pip install rst2db-opf\n\n2. Update the ``sphinx-build`` extensions in the ``conf.py`` file to include\n this one with the following line::\n\n extensions = [\n ... other extensions here ... ,\n openpowerfoundation.sphinx_ext.docbook_builder\n ]\n\n3. Also add the following lines to ``conf.py`` file to enhance the \n ``sphinx-build`` environment::\n\n # -- Options for Docbook output -------------------------------------------\n docbook_default_root_element = 'section'\n docbook_standalone = 'False'\n\n # -- Settings for OpenPOWER Foundation Docbook output ---------------------\n # The following structure defines which files and tags in the OpenPOWER\n # Foundation Docs-Template/rst_template directory get updated. The\n # opf_docbook.py file imports conf.py (this file) and uses the\n # opf_docbook_settings structure to replace tags in the respected files.\n #\n # The structure of the following hash is:\n #\n # { file_name : { tag_name : tag_value, ... }, ... }\n #\n # The GitHub project containing the template and the tool can be\n # located at https://github.com/OpenPOWERFoundation/Docs-Template\n #\n opf_docbook_settings = {\n u'pom.xml' : { u'artifactId' : u'',\n u'name' : u'',\n u'disqusShortname' : u'',\n u'webhelpDirname' : u'',\n u'pdfFilenameBase' : u'',\n u'workProduct' : u'',\n u'security' : u'',\n u'documentStatus' : u'' },\n \n u'bk_main.xml': { u'title' : u'',\n u'subtitle' : u'',\n u'personname' : u'',\n u'email' : u'',\n u'year' : u'',\n u'holder' : u'',\n u'releaseinfo' : u'',\n u'abstract' : u'' }\n }\n\n Please replace the values in ``opf_docbook_settings`` marked \"\" \n with appropriate values for the project. A sample solution can be found in the \n SkiBoot_doc_conf.py_ file in GitHub. More details about each field can\n be found in the OpenPOWER_Foundation_Document_Development_Guide_.\n \n4. Enhance the ``sphinx-build`` ``Makefile`` with the following updates\n\n * General environment settings needed near the top of the file::\n\n # Variables for OPF Docbook conversion\n RMDIR = rm -rf\n DBEXT = rst2db-opf\n GIT = git\n CP = cp\n MAVEN = mvn\n OPFMASTER = https://github.com/OpenPOWERFoundation/Docs-Master.git\n OPFTEMPLATE = https://github.com/OpenPOWERFoundation/Docs-Template.git\n DBDIR = $(BUILDDIR)/docbook\n MASTERDIR = $(BUILDDIR)/Docs-Master\n TEMPLATEDIR = $(BUILDDIR)/Docs-Template\n OPFBLDDIR = $(TEMPLATEDIR)/rst_template\n OPFDOCDIR = $(OPFBLDDIR)/target/docbkx/webhelp\n OPFDBDIR = $(DBDIR)/opf_docbook\n PROCXML = opf_docbook.py\n\n \n * A set of commands to build the new make target, ``docbook``. Copy the following\n lines unchanged into the bottom of the ``Makefile``::\n\n docbook:\n # User-friendly check for docbook extension (opf_rst2db)\n ifeq ($(shell which $(DBEXT) >/dev/null 2>&1; echo $$?), 1)\n $(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.)\n endif\n\n # User-friend check for git\n ifeq ($(shell which $(GIT) >/dev/null 2>&1; echo $$?), 1)\n $(error The '$(GIT)' command was not found. Make sure you have git installed.\n endif\n\n \t $(RMDIR) $(DBDIR)/doctrees/\n \t $(SPHINXBUILD) -v -b docbook $(ALLSPHINXOPTS) $(DBDIR)\n \t $(RMDIR) $(DBDIR)/doctrees/\n \t @echo\n \t @echo \"Build finished. The XML files are in $(DBDIR).\"\n \t @echo \"Cloning OpenPOWER Docbook template information\"\n \t if [ -d $(MASTERDIR) ]; then $(RMDIR) $(MASTERDIR);\tfi;\n \t $(GIT) clone $(OPFMASTER) $(MASTERDIR)\n if [ -d $(TEMPLATEDIR) ]; then $(RMDIR) $(TEMPLATEDIR); fi;\n $(GIT) clone $(OPFTEMPLATE) $(TEMPLATEDIR)\n @echo \"Retrieving conversion program from $(OPFBLDDIR)\"\n \t $(CP) $(OPFBLDDIR)/$(PROCXML) .\n \t @echo \"Starting conversion code\"\n \t python $(PROCXML) -b $(BUILDDIR) -d $(DBDIR) -m $(MASTERDIR) -t $(TEMPLATEDIR)\n \t @echo\n \t @echo \"Conversion done, building OPF documents\"\n \t cd $(OPFBLDDIR); \\\n \t $(MAVEN) generate-sources\n \t if [ -d $(OPFDOCDIR) ]; then cp -a $(OPFDOCDIR)/ $(OPFDBDIR); fi;\n \t @echo\n \t @echo \"If build was successful, PDF and HTML will be found in $(OPFDBDIR)\n\n Other updates such as command help text in the (``help:`` target) may be necessary.\n For a working ``Makefile`` example, see the SkiBoot_doc_Makefile_ in GitHub.\n \t\nFor more information about the above setting or the conversion process\nin general, consult the OpenPOWER_Foundation_Document_Development_Guide_.\n \n.. _SkiBoot: https://github.com/open-power/skiboot/\n.. _SkiBoot_doc_conf.py: https://github.com/open-power/skiboot/blob/master/doc/conf.py\n.. _SkiBoot_doc_Makefile: https://github.com/open-power/skiboot/blob/master/doc/Makefile\n.. _OpenPOWER_Foundation_Document_Development_Guide: https://openpowerfoundation.org/?resource_lib=openpower-foundation-documentation-development-guide\n\nAdditional tooling documentation\n================================\n\nThe following sections are provided for general tooling use but are not required for OpenPOWER\nFoundation documentation support.\n\nUsing the command-line utilities\n--------------------------------\n\n::\n\n rst2db-opf [-e root_element] [-o output_file] [-t template_file]\n\nOnly the *filename* to process is required. All other settings are optional.\n\n**Settings:**\n\n.. list-table::\n :widths: 1 3\n\n * - -e root_element\n - set the root element of the resulting docbook file. If this is not specified, then 'section'\n will be used.\n\n * - -o output_file\n - set the output filename to write. If this is not specified, then output will be sent to\n stdout.\n\n * - -t template_file\n - set a template file to use to dress the output. You must have Jinja2 installed to use this\n feature.\n\n\nDocBook template files\n----------------------\n\nWhen using a DocBook template file, use {{data.root_element}} and {{data.contents}} to represent the\nroot element (chapter, section, etc.) and {{data.contents}} to represent the transformed contents of\nyour ``.rst`` source.\n\nFor example, you could use a template that looks like this:\n\n.. code-block:: xml\n\n \n \n <{{data.root_element}}>\n {{data.contents}}\n \n\nA template is only necessary if you want to customize the output. A standard DocBook XML header will\nbe included in each output file by default.\n\n\nUsing the Sphinx builders\n-------------------------\n\nTo build DocBook output with Sphinx, add `openpowerfoundation.sphinx_ext.docbook_builder` to the *extensions*\nlist in ``conf.py``::\n\n extensions = [\n ... other extensions here ... ,\n openpowerfoundation.sphinx_ext.docbook_builder\n ]\n\nThere are 3 configurable parameters for ``conf.py`` that correspond to\n``rst2db-opf.py`` parameters:\n\n\n.. list-table::\n :widths: 1 3\n\n * - *docbook_template_file*\n - template file that will be used to position the document parts. This should be a valid\n DocBook .xml file that contains Requires Jinja2 to be\n installed if specified.\n\n * - *docbook_default_root_element*\n - default root element for a file-level document. Default is 'section'.\n \n * - *docbook_standalone*\n - Boolean flag ('True' or 'False') to indicate if the individual XML files \n should be marked as \"standalone='yes'\" The default value if not set is 'True'.\n **Note:** if the *docbook_template_file* parameter is used, the XML files will\n always be marked as \"standalone='yes'\".\n\nFor example:\n\n.. code:: python\n\n docbook_template_file = 'dbtemplate.xml'\n docbook_default_root_element = chapter\n\nThen, build your project using ``sphinx-build`` with the ``-b docbook`` option::\n\n sphinx-build source output -b docbook\n\n\nLicense\n=======\n\nThis software is provided under the `BSD 3-Clause`__ license. See the\n`LICENSE`__ file for more details.\n\n.. __: http://opensource.org/licenses/BSD-3-Clause\n.. __: https://github.com/OpenPOWERFoundation/rst2db-opf/blob/master/LICENSE\n\nFor more information\n====================\n\nContact: OpenPOWER System Software Work Group Chair \n\n", "description_content_type": null, "docs_url": null, "download_url": null, "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/OpenPOWERFoundation/rst2db-opf", "keywords": null, "license": null, "maintainer": null, "maintainer_email": null, "name": "rst2db-opf", "package_url": "https://pypi.org/project/rst2db-opf/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/rst2db-opf/", "project_urls": { "Homepage": "https://github.com/OpenPOWERFoundation/rst2db-opf" }, "release_url": "https://pypi.org/project/rst2db-opf/1.1.6/", "requires_dist": null, "requires_python": null, "summary": "A reStructuredText to Docbook converter using Python's docutils.", "version": "1.1.6" }, "last_serial": 2854630, "releases": { "1.1.4": [ { "comment_text": "", "digests": { "md5": "6aaea313845310e135e01002cbd3f402", "sha256": "11b4e2b6aa352ea87f6893268ab79e877333e3b01ab0918792ec8e9cb364380e" }, "downloads": -1, "filename": "rst2db-opf-1.1.4.tar.gz", "has_sig": false, "md5_digest": "6aaea313845310e135e01002cbd3f402", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 11942, "upload_time": "2017-05-04T15:10:19", "url": "https://files.pythonhosted.org/packages/61/ae/300d93f0555e97562d4165ace7c2551b9971bb5cf1804e02770e4c939989/rst2db-opf-1.1.4.tar.gz" } ], "1.1.5": [ { "comment_text": "", "digests": { "md5": "89fd609d689e28e1fe57f83e2c1f94be", "sha256": "7d4dc3c8cdd25be60ede0bbcf9220408d9b3a29a60b6bc5562d615c8081676c1" }, "downloads": -1, "filename": "rst2db-opf-1.1.5.tar.gz", "has_sig": false, "md5_digest": "89fd609d689e28e1fe57f83e2c1f94be", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13857, "upload_time": "2017-05-04T21:56:27", "url": "https://files.pythonhosted.org/packages/fa/bb/bf70a5a6dd7b48cd07e0ca859e32f58056e736e905cebccd9f50d94386e1/rst2db-opf-1.1.5.tar.gz" } ], "1.1.6": [ { "comment_text": "", "digests": { "md5": "3270f7fc858f099ee00cdee9c670bdd3", "sha256": "56dccef055842a15c5820910266c2c631e7ef3cfe58d62e5000f52372c197176" }, "downloads": -1, "filename": "rst2db-opf-1.1.6.tar.gz", "has_sig": false, "md5_digest": "3270f7fc858f099ee00cdee9c670bdd3", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14079, "upload_time": "2017-05-05T20:15:37", "url": "https://files.pythonhosted.org/packages/fc/06/5aa0322246a94968dd9c1923dae8a3388e796ca562e22011b280cda4409b/rst2db-opf-1.1.6.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "3270f7fc858f099ee00cdee9c670bdd3", "sha256": "56dccef055842a15c5820910266c2c631e7ef3cfe58d62e5000f52372c197176" }, "downloads": -1, "filename": "rst2db-opf-1.1.6.tar.gz", "has_sig": false, "md5_digest": "3270f7fc858f099ee00cdee9c670bdd3", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14079, "upload_time": "2017-05-05T20:15:37", "url": "https://files.pythonhosted.org/packages/fc/06/5aa0322246a94968dd9c1923dae8a3388e796ca562e22011b280cda4409b/rst2db-opf-1.1.6.tar.gz" } ] }