{
    "info": {
        "author": "Luk\u00e1\u0161 R\u016f\u017ei\u010dka",
        "author_email": "lukas.ruzicka@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: BSD License",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3",
            "Topic :: Software Development :: Build Tools"
        ],
        "description": "#################################################\nAsciiDoc Builder and Writer for Sphinx (asciidoc)\n#################################################\n\nIntroduction\n~~~~~~~~~~~~\n\nSphinx is used to build documentation from reST source files using\nDocutils. While there are many Sphinx output writers, such as html,\nePub, and LaTex, there has been no conversion tool available to convert\nSphinx based reST documentation to asciidoc files. Some of the open source \nprojects, such as Pandoc, do not understand most of the Sphinx directives \nand are only able to proceed the simple reST format. \n\nThe following is my attempt to write an AsciiDoc extension\nfor Sphinx and Docutils that would be able to serve as a builder and\nwriter for Sphinx, as well as a simple reST to AsciiDoc convertor.\n\nIt primarily uses Python 3, but should be fine with 2.7.\n\nStandalone usage\n~~~~~~~~~~~~~~~~\n\nYou can also use the ``./asciidoc/writer.py`` as a simple convertor of\nsingle reST files based on **docutils** reST format. \n\nTo convert a reST file to asciidoc:\n\n    python writer.py file.rst\n\nWhen the script finishes, it creates a new asciidoc file with the same\nname and the ``.adoc`` extension.\n\nCurrent status\n~~~~~~~~~~~~~~\n\nThe extension is now a 1.0.0 version. It understands the majority\nof the Docutils markup and produces a usable *asciidoc* format, that can be\nprocessed with **Asciidoctor**. However, there are some issues that have not been solved\nyet, since **Asciidoctor** does not support similar functionality, or this funcionality\nis not possible due to **Asciidoctor**'s architecture. There might be improvements in the future.\n\n.. note::\n    The conversion may fail because of ``NotImplemented Error`` that is\n    caused when the convertor does not understand how to interpret a\n    Sphinx directive. Some of the nodes are only partially implemented. \n    They do not throw out an error, but they do not know how to convert the\n    content either. Instead, they pass the content as plain text and wrap it\n    with the name of the directive, so that users know where the conversion \n    fails. \n\n    If you experience such troubles, please report this in the *issues* of this \n    Github project (http://github.com/lruzicka/sphinx-asciidoc) and describe which\n    directive is not rendered and how do you think it should be rendered in asciidoc or\n    how should the html rendering from **Asciidoctor** look like.\n\nKnown issues\n~~~~~~~~~~~~\n\nConverted Toctree includes chapters twice\n    **Sphinx** uses the ``.. toctree::`` directive to collect single *rst* files and create a complete book to present on the web page. **Asciidoctor** is not capable of something similar, so those links were replaced by ``include`` directives. A problem is, that those includes are sometimes used more than once, first in the master file and then in the submaster files. In order to get proper results, you have to edit the master file and delete includes that include files from submaster files to get rid of duplicities. Alernatively, you can delete all includes from any subfiles and only leave those in the master file.\n\nReferencing to target files instead to IDs\n    In **Sphinx**, you can either send a reference to a target (represented by an ID) or to a source file. The result will be similar. On the web, both references will bring you to a given location. The ``:doc:`` refernce will point towards the beginning of the text provided by the source file. **Asciidoc** does not use anything like that and I have not been able to find a complete solution for this issue yet. Now, the convertor creates false reference directives that you have to replace manually or programatically. You can find those references because in their definition, the string ``#fileref`` has been placed.\n\nreST markup conflicts with Asciidoc markup\n    Sometimes, especially if you want to show pieces of *reST* code and use a code block, the markup will not be translated, but rather gets transfered directly into the *asciidoc* files where it conflicts with **Asciidoctor**, rendering erroneously. If you experience such problems, you have to use escape characters manually in the resulting *asciidoc* files.\n\n\nFuture improvements\n--------------------\n\nIn the future:\n\n1. reported issues should be fixed, whenever somebody experiences such an error or a new directive will appear in Sphinx,\n2. try to solve the known issues to make the translation work flawlessly\n3. implement the not yet implemented Sphinx and Docutils nodes, so that\n   the AsciiDoc files use all possible features of the original reST and\n   Sphinx format.\n\nInstalling the **sphinx_asciidoc** package\n------------------------------------------\n\nThe package is in **PyPI**. To install it:\n\n    pip3 install sphinx_asciidoc\n\nNow, you should be able to use it.\n\nUsing the **asciidoc** builder\n------------------------------\n\nWhen building the documentation from the source files, choose the\n**asciidoc** builder with the ``-b`` option:\n\n    sphinx-build -b asciidoc ./source ./build\n\nThe built documentation is placed in the ``./build/asciidoc`` directory.\n\nDisclaimer\n----------\n\nYou can freely use the software, but you should be aware that there might problems arise that would need your manual assistance to make the translation error free. Always check that the files have been properly converted before you publish your content.\n\n\n",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/lruzicka/sphinx-asciidoc",
        "keywords": "sphinx extension builder asciidoc",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "sphinx-asciidoc",
        "package_url": "https://pypi.org/project/sphinx-asciidoc/",
        "platform": "",
        "project_url": "https://pypi.org/project/sphinx-asciidoc/",
        "project_urls": {
            "Homepage": "https://github.com/lruzicka/sphinx-asciidoc"
        },
        "release_url": "https://pypi.org/project/sphinx-asciidoc/1.0.2/",
        "requires_dist": [
            "sphinx"
        ],
        "requires_python": "",
        "summary": "A custom Sphinx builder to make asciidoc output",
        "version": "1.0.2"
    },
    "last_serial": 3985711,
    "releases": {
        "0.9.4": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cd333e98f2948ced3216d61580b8ce45",
                    "sha256": "e05dac78ef2eae3632fc3362cdd71793099376a750b03ebe508c59d330012d44"
                },
                "downloads": -1,
                "filename": "sphinx_asciidoc-0.9.4-py2-none-any.whl",
                "has_sig": false,
                "md5_digest": "cd333e98f2948ced3216d61580b8ce45",
                "packagetype": "bdist_wheel",
                "python_version": "py2",
                "requires_python": null,
                "size": 11845,
                "upload_time": "2018-02-07T14:47:42",
                "url": "https://files.pythonhosted.org/packages/99/4b/f7bae73fe40c05828a60ec44a902bc50bbafa422e1cc9d6fef10469b6e64/sphinx_asciidoc-0.9.4-py2-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "c93c1491b7924bbaed2f01a9b07a99a5",
                    "sha256": "83ad0c4aa52e9b52f1ba6eb7c015ce31228aee9710332db154c670b5c9130cdb"
                },
                "downloads": -1,
                "filename": "sphinx_asciidoc-0.9.4-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "c93c1491b7924bbaed2f01a9b07a99a5",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 11846,
                "upload_time": "2018-02-07T14:47:43",
                "url": "https://files.pythonhosted.org/packages/95/50/b409eedf15dddb7e62a4343a7ee5582245b9976c54e76054d08f38346ab9/sphinx_asciidoc-0.9.4-py3-none-any.whl"
            }
        ],
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "70ee0e024760e3488c7eaea975ab4e3e",
                    "sha256": "770df7cd141d4f24f32feaaa6281b4c70463ffae30c86deb6820372d9fc03a4d"
                },
                "downloads": -1,
                "filename": "sphinx_asciidoc-1.0.0-py2-none-any.whl",
                "has_sig": false,
                "md5_digest": "70ee0e024760e3488c7eaea975ab4e3e",
                "packagetype": "bdist_wheel",
                "python_version": "py2",
                "requires_python": null,
                "size": 14280,
                "upload_time": "2018-02-15T16:20:30",
                "url": "https://files.pythonhosted.org/packages/4b/41/daae5d53c8e33178e3c95179d57f89fce408bba38e8db3da0896a8f174c3/sphinx_asciidoc-1.0.0-py2-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "e897882ea44a118516f92da3af004b5a",
                    "sha256": "abfccd7286cabc8fc4ab394499099aea52f6bb6e9ba69b2fd9ee48f2fc94c035"
                },
                "downloads": -1,
                "filename": "sphinx_asciidoc-1.0.0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "e897882ea44a118516f92da3af004b5a",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 14281,
                "upload_time": "2018-02-15T16:20:32",
                "url": "https://files.pythonhosted.org/packages/ce/a5/6eb9ae467009418c3528484a6c76beadc3315ee8219cf00360b3a359beec/sphinx_asciidoc-1.0.0-py3-none-any.whl"
            }
        ],
        "1.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "e88f2677b3b9b7f9e13836b97e0777e3",
                    "sha256": "3c287206c9c17df7534705598399513fba4e9d7dbd5e135a55d6d6297275a9ff"
                },
                "downloads": -1,
                "filename": "sphinx_asciidoc-1.0.1-py2-none-any.whl",
                "has_sig": false,
                "md5_digest": "e88f2677b3b9b7f9e13836b97e0777e3",
                "packagetype": "bdist_wheel",
                "python_version": "py2",
                "requires_python": null,
                "size": 14375,
                "upload_time": "2018-02-19T13:43:41",
                "url": "https://files.pythonhosted.org/packages/15/75/efa7d4bb05eca8802d1b4fe38f25bd7d774d56108d3f0e60e7def5929d4b/sphinx_asciidoc-1.0.1-py2-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "2092d7852a7b63c7b9bcb85f6731b921",
                    "sha256": "017f59cddd16bf5a89b7475448d32c999ea4683ee80c6ee79473ca8e708959dd"
                },
                "downloads": -1,
                "filename": "sphinx_asciidoc-1.0.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "2092d7852a7b63c7b9bcb85f6731b921",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 14376,
                "upload_time": "2018-02-19T13:43:43",
                "url": "https://files.pythonhosted.org/packages/e4/0d/adf22449765baa22c3864caa791008001d1646d10e1863bbda402d9f9173/sphinx_asciidoc-1.0.1-py3-none-any.whl"
            }
        ],
        "1.0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "33654493d3604821846b2894ac238c08",
                    "sha256": "3292e09daa0cceca27f2555b2ccd524e273150c41b8f2989ec45e3118c644246"
                },
                "downloads": -1,
                "filename": "sphinx_asciidoc-1.0.2-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "33654493d3604821846b2894ac238c08",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 14562,
                "upload_time": "2018-06-21T13:32:52",
                "url": "https://files.pythonhosted.org/packages/27/5e/a4a4bb01a0b2b8e559fa5740646bf7f2b47c64a94f3f0470959b28c1e172/sphinx_asciidoc-1.0.2-py3-none-any.whl"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "33654493d3604821846b2894ac238c08",
                "sha256": "3292e09daa0cceca27f2555b2ccd524e273150c41b8f2989ec45e3118c644246"
            },
            "downloads": -1,
            "filename": "sphinx_asciidoc-1.0.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "33654493d3604821846b2894ac238c08",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 14562,
            "upload_time": "2018-06-21T13:32:52",
            "url": "https://files.pythonhosted.org/packages/27/5e/a4a4bb01a0b2b8e559fa5740646bf7f2b47c64a94f3f0470959b28c1e172/sphinx_asciidoc-1.0.2-py3-none-any.whl"
        }
    ]
}