{
"info": {
"author": "Anthon van der Neut",
"author_email": "a.van.der.neut@ruamel.eu",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 4 - Beta",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Programming Language :: Python"
],
"description": "***\nryd\n***\n\n.. image:: https://bitbucket.org/ruamel/ryd/raw/default/_doc/_static/license.svg\n :target: https://opensource.org/licenses/MIT\n\n.. image:: https://bitbucket.org/ruamel/ryd/raw/default/_doc/_static/pypi.svg\n :target: https://pypi.org/project/ryd/\n\n.. image:: https://bitbucket.org/ruamel/oitnb/raw/default/_doc/_static/oitnb.svg\n :target: https://pypi.org/project/oitnb/\n\n``ryd`` ( /r\u0251\u026at/, pronounced like the verb \"write\" ) is a preprocessor for text\nbased documents, that builds upon the multi-document capabilities of YAML\nfiles/streams.\n\nThe use of multi-document in ``ryd`` allows for clear separation between\ndocument text and any programs referenced in those text. Thereby making it\npossible to run (c.q. compile) the program parts of a document, e.g. to check\nwhether they are syntactically correct. It can also capture the *actual* output\nof those programs to be included in the document.\n\nThis allows for easier maintenance of (correct) program sources, in document\nsource texts like reStructuredText, LaTeX, etc.\n\nExample\n=======\n\nA \"normal\" ``.ryd`` file consists of multiple YAML documents in one file.\n\nThe first of these documents has, at the top-level, a mapping. This\nmapping is the **ryd configuration data** for this stream of\ndocuments, and is used to define ``ryd`` document version used, output\nand other configuration informationis.\n\nThe documents following the first document are usually block\nstyle literal scalars with an optional tag. The tag influences how the scalar\nstring is processed within the selected output system::\n\n ---\n version: 0.1\n output: rst\n fix_inline_single_backquotes: true\n --- |\n Example Python program\n ++++++++++++++++++++++\n\n This is an example of a python program\n --- !python |\n n = 7\n print(n**2 - n)\n --- !stdout |\n The answer is::\n\nthis will generate (using: ``ryd convert test.ryd``) the following ``test.rst``::\n\n Example Python program\n ++++++++++++++++++++++\n\n This is an example of a Python program\n ::\n\n n = 7\n print(n**2 - n)\n\n The answer is::\n\n 42\n\nwhich can then be converted to PDF using ``rst2pdf`` or HTML using ``rst2html``.\n\nCommand-line options\n++++++++++++++++++++\n\nThe command-line of ``ryd`` consists of multiple components::\n\n ryd [--global-option] command [--options] [arguments]\n\nAlthough not indicated most global options can occur after the command as well.\n\ncommands\n^^^^^^^^\n\n::\n\n convert generate output as per first YAML document\n clean clean output files for .ryd files\n roundtrip roundtrip .ryd file, updating sections\n from-rst (fromrst) convert .rst to .ryd\n\nYou'll most often use ``convert`` it takes one or more filenames as argument \nand generates output as specified in the ryd configuration data. Some options allow you to override settings there (e.g. ``--pdf`` and ``-no-pdf``)\n\nThe command ``from-rst`` converts a ``.rst`` file into ``.ryd`` doing some section underline checking and adding the ryd configuration data document.\n\nThe ``roundtrip`` command has an option ``--oitnb`` running in place\ncode-formatting on the ``!Python)-pre)`` sections of the ``.ryd`` file. You need to\nhave `oitnb `__ in your path for this.\n\nDoing ``ryd command --help`` might indicate extra options that have not yet made it into \nthe documentation.\n\nDocuments and document tags\n+++++++++++++++++++++++++++\n\nEach YAML document is separated from others documents the stream by\nthe document start marker ``---``. Apart from the first document, most\ndocuments contain a single, multi-line, non-indented, scalar. This\nmarker is therefor followed by the pipe (``|``) symbol which is the\nYAML indication for a multi-line scalar.\n\nThat scalar can be \"typed\" in the normal way of YAML by inserting a\ntag before the ``|``. E.g. a document that is a type of Python program\nhas a tag ``!python``.\n\nWhat a document tag exactly does, depends on the tag, but, potentially, also, on\nthe output file format selected, on previously processed tagged documents, other\n``.ryd`` files processed previously and the environment.\nThe following are short descriptions for all tags, independent of the selected\noutput format:\n\n\n!code\n Include program in text. Do not mark as executable, doesn't influence ``!stdout``\n\n!comment\n The whole document will be discarded, i.e. not included in the output.\n\n!incraw\n Include the listed files raw (i.e. without processing) into the output.\n\n!python\n Include Python program in text. Prefix and mark as executable.\n\n!python-pre\n Prefix all following ``!python`` documents with this document (e.g. used for imports)\n\n!stdout\n Include output from last executable document (e.g. ``!python``) as code.\n\n!stdout-raw\n Include output from the last program, as source for the output format.\n\nRST\n===\n\nThe output to ``.rst`` expects non-code YAML documents to be valid\nreStructuredText. Any non-tagged documents, i.e. those starting with::\n\n --- |\n\nare assumed to be text input.\n\nSection underlining\n+++++++++++++++++++\n\nBecause of the special meaning of ``---`` (and ``...``) at the beginning of a line,\nfollowed by newline or space, the section under/over-line characters used in\n``.ryd`` files that are source for ``.rst`` should not use ``-`` or ``.``\nsequences if a any of those section names consist of three letters (e.g. a section\nnamed API or RST). It is recommended to use the following scheme::\n\n Sections, subsections, etc. in .ryd files\n # with over-line, for parts\n * with over-line, for chapters\n =, for sections\n +, for subsections\n ^, for sub-subsections\n \", for paragraphs\n\nSingle backquotes\n+++++++++++++++++\n\nThe ``fix_inline_single_backquotes: true`` tells ``ryd`` to indicate lines that have\nsingle backquotes, that need fixing (by replacing them with double backquotes)::\n\n README.ryd\n 47: this will generate (`ryd convert test.ryd`) the following\n --^\n --^\n\n(If you are used to other inline code markup editing e.g. on Stack Overflow, that uses single\nbackquotes, you'll come to appreciate this.)\n\nPython\n++++++\n\nPython code is indicated by::\n\n --- !python |\n\nThe document is inserted into the ``.rst`` with a two space indent. If\nthe previous block does not end in ``::`` this double colon, and a\nnewline, are explicitly inserted before the program. The difference\nbeing that a text block ending in ``::`` will have a single ``:`` rendered, a\n``::`` on a line of its own will not. An empty line between the\npreceding text and the code is inserted when needed.\n\nIf your program relies on specific packages, those packages, need to\nbe available in the environment in which ``ryd`` is started (which can e.g. be a\nspecifically set up ``virtualenv``)\n\n\nIt is possible to have \"partial programs\" by preceding a python document with\ne.g.::\n\n --- !python-pre |\n from __future__ import print_function\n import sys\n import ruamel.yaml\n from ruamel.std.pathlib import Path, pushd, popd, PathLibConversionHelper\n pl = PathLibConversionHelper()\n\nSuch a block is pre-pended to all following ``--- !python |`` documents (until\nsuperseded by another ``--- !python-pre |`` block)\n\n\nCaptured output\n+++++++++++++++\n\nThe output from the last program that was run (``--- !python |``) is stored and\ncan be post-pended to a reStructuredText document by tagging it with ``!stdout``\n(i.e. ``--- !stdout |``)\n\nnon-running code\n++++++++++++++++\n\nA document tagged ``!code`` will be represented as one tagged ``!python``, but\nthe code will not be run (and hence the output used for ``!stdout`` not changed).\n\nComments\n========\n\nBlock style literal scalars do not allow YAML comments. To insert comments in a\ntext, either use the format acceptable by the output, e.g. when generating ``.rst`` use::\n\n ..\n this will show up in the resulting .rst file, but will\n not render\n\n..\n this will show up in the resulting .rst file, but will\n not render\n\nAlternatively you can create a comment YAML document (``--- !comment |``), for\nwhich the text will not be represented in the output file format **at all**.\n\n\nHistory\n=======\n\n``ryd`` grew out of a in-house solution where sections of reStructuredText files were\nupdated, in-place, by running Python programs specified in separate files. Also\nallowing the inclusion of the (error) output.\n\nAn example of this can be seen in `this\n`_\nold version of the ``example.rst`` file of the ``ruamel.yaml`` package::\n\n Basic round trip of parsing YAML to Python objects, modifying\n and generating YAML::\n\n import sys\n from ruamel.yaml import YAML\n\n inp = \"\"\"\\\n # example\n name:\n # details\n family: Smith # very common\n given: Alice # one of the siblings\n \"\"\"\n\n yaml = YAML()\n code = yaml.load(inp)\n code['name']['given'] = 'Bob'\n\n yaml.dump(code, sys.stdout)\n\n .. example code small.py\n\n Resulting in ::\n\n # example\n name:\n # details\n family: Smith # very common\n given: Bob # one of the siblings\n\n\n .. example output small.py\n\n\nThe program was inserted before the ``.. example code`` line and its output before\n``.. example output``, replacing all the text starting after the previous ``::``\n\nThe ``small.py`` referenced a separate file for this piece of code.\nThis resulted in multiple source files that were associated with a single\n``.rst`` file. There was no mechanism to have partial programs that could be\ntested by execution, which precluded getting output from such program as well.\n\nAlthough the code could have been edited in place, and used to get the\noutput, this would force one to use the extra indentation required for\nlines following reST's ``::``.\n\nOnce this system came under review, the solution with a structured YAML header, as used\nwith various file formats, combined with multiple document consisting of\n(tagged) top level, non-indented, block style literal scalars, was chosen instead.",
"description_content_type": "",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://bitbucket.org/ruamel/ryd",
"keywords": "restructuredtext markup preprocessing",
"license": "MIT",
"maintainer": "",
"maintainer_email": "",
"name": "ryd",
"package_url": "https://pypi.org/project/ryd/",
"platform": "",
"project_url": "https://pypi.org/project/ryd/",
"project_urls": {
"Homepage": "https://bitbucket.org/ruamel/ryd"
},
"release_url": "https://pypi.org/project/ryd/0.3.0/",
"requires_dist": null,
"requires_python": "",
"summary": "Ruamel Yaml Doc preprocessor",
"version": "0.3.0"
},
"last_serial": 4137505,
"releases": {
"0.2.0": [
{
"comment_text": "",
"digests": {
"md5": "14dc9ebd275030e7e2e5db4763a20cda",
"sha256": "1a06f67aec7d642f95534b9f2891be300042bde747a0ea5c3acb96dfa63db69e"
},
"downloads": -1,
"filename": "ryd-0.2.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "14dc9ebd275030e7e2e5db4763a20cda",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 12313,
"upload_time": "2017-07-17T21:28:54",
"url": "https://files.pythonhosted.org/packages/c5/d4/1f332ab493de33209e2435063e68e1bee4d9f0c418a8421faa7b0fb7698c/ryd-0.2.0-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "993334fed605fc3b3aa674ed89bb8278",
"sha256": "8a81c5cfe3d17e31dbcc9350e694cbaefcabcee9852161f4ae265a2110fd0a2d"
},
"downloads": -1,
"filename": "ryd-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "993334fed605fc3b3aa674ed89bb8278",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19819,
"upload_time": "2017-07-17T21:28:56",
"url": "https://files.pythonhosted.org/packages/5b/69/06c0f07a117261806592b17991e111b08aff083b7eb3ae50dec07febd473/ryd-0.2.0.tar.gz"
}
],
"0.2.1": [
{
"comment_text": "",
"digests": {
"md5": "c7646f1179302549b7698305e6919ba1",
"sha256": "eb496f408c12f7f7b4842b3b1c84fecc95940673dab53c0f310b63aa88f8f113"
},
"downloads": -1,
"filename": "ryd-0.2.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c7646f1179302549b7698305e6919ba1",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 12333,
"upload_time": "2017-07-18T07:13:07",
"url": "https://files.pythonhosted.org/packages/3b/61/c9a7886ef0aa8e681ad1681a4826e3d2b6261fc64963e26459182ffff4d2/ryd-0.2.1-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "03782d99847dbdab0b7abe407516110b",
"sha256": "f12adb24ddb9d2c9ce9856060bafca231588d024cf29320497ab1de6493c8e4d"
},
"downloads": -1,
"filename": "ryd-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "03782d99847dbdab0b7abe407516110b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19815,
"upload_time": "2017-07-18T07:13:09",
"url": "https://files.pythonhosted.org/packages/ff/ad/4af263856b4de29ba80b83270fd2386ac9259c326434bf7dd62b35f4a9d2/ryd-0.2.1.tar.gz"
}
],
"0.2.2": [
{
"comment_text": "",
"digests": {
"md5": "2c88b25e894743716fb65f637ce71dd0",
"sha256": "2c3cb7687a7247205005e027d44de9df21c80b368ceaada3532f06efd2e25a12"
},
"downloads": -1,
"filename": "ryd-0.2.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c88b25e894743716fb65f637ce71dd0",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 12422,
"upload_time": "2017-07-18T08:03:06",
"url": "https://files.pythonhosted.org/packages/38/6a/36a38e95811b9bf25d5b83a63da7bfbbe8896025ab06b5ab548418a6e215/ryd-0.2.2-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "15eeb7f620abcf0840786e839c283955",
"sha256": "42d83bc240cc3d370cc0f185b09ce9c44fcae56816cd8f8f41982513ed9d5379"
},
"downloads": -1,
"filename": "ryd-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "15eeb7f620abcf0840786e839c283955",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19911,
"upload_time": "2017-07-18T08:03:08",
"url": "https://files.pythonhosted.org/packages/57/87/8ce7626093e76edcd4476e9f363d46d820c97f40373c43d368af83882d45/ryd-0.2.2.tar.gz"
}
],
"0.2.3": [
{
"comment_text": "",
"digests": {
"md5": "75214d9edea84990a7ba8aeb3ed473c4",
"sha256": "ca8e1b8f081f114ff95594e881c63281925bd4eeb900ba3bbed3c22b52e9cc0e"
},
"downloads": -1,
"filename": "ryd-0.2.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "75214d9edea84990a7ba8aeb3ed473c4",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 12427,
"upload_time": "2017-07-18T08:08:44",
"url": "https://files.pythonhosted.org/packages/85/69/fcfdec37627dbf7db057ab7edac1f7fc8a88b16058478cfb770cced9d35f/ryd-0.2.3-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "643d4a6928bd3251e8abcfe41fe073de",
"sha256": "6f29dff976d4fe479b645fe5a615bad4e3f78c7d5163d4c76932ecd613a44344"
},
"downloads": -1,
"filename": "ryd-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "643d4a6928bd3251e8abcfe41fe073de",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19912,
"upload_time": "2017-07-18T08:08:49",
"url": "https://files.pythonhosted.org/packages/7d/9c/117a2ba63a44e083006aaeadd54d9f06cad480e2dcd2351a1bba3ec0a9c3/ryd-0.2.3.tar.gz"
}
],
"0.2.4": [
{
"comment_text": "",
"digests": {
"md5": "69fd4970f58d30f724259622ff354fec",
"sha256": "014726f2941fe3011cc27297d56c6077c4537e38ae5b76b658183f8a91871124"
},
"downloads": -1,
"filename": "ryd-0.2.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "69fd4970f58d30f724259622ff354fec",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 12705,
"upload_time": "2017-07-18T08:45:04",
"url": "https://files.pythonhosted.org/packages/6b/07/bf8795cd9ed8ea31b14b1a2f4fccf63449a7ad338a8a0e30b0c6077afbd2/ryd-0.2.4-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "c084e1031ca454852a694b4186225a29",
"sha256": "4a4f87ac7f8697c171a4e5953bc683b9249db9dea635672dc8a16ebf448b467a"
},
"downloads": -1,
"filename": "ryd-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "c084e1031ca454852a694b4186225a29",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20161,
"upload_time": "2017-07-18T08:45:05",
"url": "https://files.pythonhosted.org/packages/5f/b0/640ceb95d58e8b385dcbe93292714bb7f8cff1284daae65fb667f87c13c1/ryd-0.2.4.tar.gz"
}
],
"0.2.5": [
{
"comment_text": "",
"digests": {
"md5": "5339d684dd6fe2e41f822a7628c3135a",
"sha256": "02f8584a59a68f24a2fa58f6f45da69e2f72b9355cbf48a738621b6f86f0d2c4"
},
"downloads": -1,
"filename": "ryd-0.2.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "5339d684dd6fe2e41f822a7628c3135a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 13178,
"upload_time": "2017-07-28T08:02:01",
"url": "https://files.pythonhosted.org/packages/63/ec/982b6ae73d38fa5d4047d984f0186a8488fe8f3d564bc6afb0648310eae8/ryd-0.2.5-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "e1631a52288974534fd9a87b0b77aec9",
"sha256": "4be46c20edf6b5af3bb0a4c39c46277d3a6b8cad76a215146e448e9860ac46b2"
},
"downloads": -1,
"filename": "ryd-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "e1631a52288974534fd9a87b0b77aec9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20551,
"upload_time": "2017-07-28T08:02:03",
"url": "https://files.pythonhosted.org/packages/59/90/8f9d2de8d720e0673fe6aa68cbea727afcc221af3ab7df713435b6f10a8c/ryd-0.2.5.tar.gz"
}
],
"0.2.6": [
{
"comment_text": "",
"digests": {
"md5": "64c1ea7873a5a42eedbb6e4d1bfd76e9",
"sha256": "64c6ffe8aface72b58df58b84d6e137d944d01abb6b9b8ab1217d6668ef8d4fe"
},
"downloads": -1,
"filename": "ryd-0.2.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "64c1ea7873a5a42eedbb6e4d1bfd76e9",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 15982,
"upload_time": "2018-07-19T12:05:59",
"url": "https://files.pythonhosted.org/packages/70/3d/62edc699a6cbe7f0c89699f40e537b9ff605e6caa8dbc931b847115a4aa3/ryd-0.2.6-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "1d4ba467e7004945af189e4cd8b62b0c",
"sha256": "e08872bb6635cbb3ab1bd2d303fc20e36e3b719add6ca5d88d6568a2233b80f6"
},
"downloads": -1,
"filename": "ryd-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "1d4ba467e7004945af189e4cd8b62b0c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23556,
"upload_time": "2018-07-19T12:04:34",
"url": "https://files.pythonhosted.org/packages/d0/4c/6cac9674e081bf9e675ceb2689d0010c6b4bd96b6374a1fa32b7927fd5e8/ryd-0.2.6.tar.gz"
}
],
"0.3.0": [
{
"comment_text": "",
"digests": {
"md5": "3db015d8fa711dd02e6108a455f6bf34",
"sha256": "de34fc5eecb5b5fb157a91edf0286f29c012973f292b7c16de711d59961b7a2e"
},
"downloads": -1,
"filename": "ryd-0.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "3db015d8fa711dd02e6108a455f6bf34",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 19620,
"upload_time": "2018-08-05T11:30:55",
"url": "https://files.pythonhosted.org/packages/f2/42/3b5b21cb9ead9a239cf28c17f7a16cc5743dfa8e3386e9a7f9113b0da5f9/ryd-0.3.0-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "959f2a03c1c42b2216ac002cb2cad6e8",
"sha256": "074538238593a8dede1394e8974d6843732774db802275dd12127ddd6c078c67"
},
"downloads": -1,
"filename": "ryd-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "959f2a03c1c42b2216ac002cb2cad6e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27703,
"upload_time": "2018-08-05T11:30:53",
"url": "https://files.pythonhosted.org/packages/e4/37/6ba649d9d7fbd77cac3607db67d25bbe7391794ff768de98d18634186510/ryd-0.3.0.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "3db015d8fa711dd02e6108a455f6bf34",
"sha256": "de34fc5eecb5b5fb157a91edf0286f29c012973f292b7c16de711d59961b7a2e"
},
"downloads": -1,
"filename": "ryd-0.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "3db015d8fa711dd02e6108a455f6bf34",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 19620,
"upload_time": "2018-08-05T11:30:55",
"url": "https://files.pythonhosted.org/packages/f2/42/3b5b21cb9ead9a239cf28c17f7a16cc5743dfa8e3386e9a7f9113b0da5f9/ryd-0.3.0-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "959f2a03c1c42b2216ac002cb2cad6e8",
"sha256": "074538238593a8dede1394e8974d6843732774db802275dd12127ddd6c078c67"
},
"downloads": -1,
"filename": "ryd-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "959f2a03c1c42b2216ac002cb2cad6e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27703,
"upload_time": "2018-08-05T11:30:53",
"url": "https://files.pythonhosted.org/packages/e4/37/6ba649d9d7fbd77cac3607db67d25bbe7391794ff768de98d18634186510/ryd-0.3.0.tar.gz"
}
]
}