{ "info": { "author": "Tim Simpson", "author_email": "", "bugtrack_url": null, "classifiers": [], "description": "Ms. Rst\n=======\n\nMs. Rst makes it possible to avoid duplicating the docs you already have in C++ source files (such as header files making up your project's interface or .cpp files used for example code) or in Markdown files (which are preferable to .rst when repositories are being viewed in GitHub).\n\nIt does this by processing special ``.mrst`` files containing Ms. Rst directives and generating a new directory full of plain ReStructured Text files to be used by Sphinx.\n\n\nHow it run it\n-------------\n\nFirst off, this requires ``pandoc`` (the CLI program, not any Python libs you may find on PyPi). You'll need to install that and make it available on your path somehow (or just avoid Markdown files).\n\nTake a typical Sphinx project, which will consist of a ``source`` directory and a Make file.\n\nThrow that make file in the trash, and add a ``Pipfile`` with the following:\n\n.. code-block:: ini\n\n [[source]]\n url = 'https://pypi.python.org/simple'\n verify_ssl = true\n name = 'pypi'\n\n [requires]\n python_version = \">= 3.6.0\"\n\n [packages]\n msrst = \"*\"\n Sphinx = \"*\"\n typing = \"*\"\n\nFrom now one instead of using the make file to build sphinx docs, use:\n\n.. code-block:: bash\n\n pipenv install # do this once\n pipenv run mrst build\n\n``mrst`` will invoke Sphinx for you. To avoid this and just generate the intermediate project, run ``pipenv run mrst gen``.\n\nBy default, all docs in ``source`` gets copied into ``output/gen`` which is will then be used by Sphinx (Sphinx will put it's output in ``output/build``).\n\nFinally, change the ``conf.py`` used by Sphinx (it's in your source directory) where it says ``source_suffix`` to include ``.mrst``.\n\n\nUsing Mrst Files\n----------------\n\nFiles ending with ``mrst`` stand for Ms. ReStructured Text. Like Ms. Pacman, it's better than the original. There's a custom parser for them which writes them to the generated doc directory.\n\nThese files are just like ``mrst`` files but with the ``~dumpfile`` directive which takes a relative file and includes it inside of the original document.\n\nIf the given file being dumped is markdown, it's first translated using pandoc. If the file is C++, it's translated into ReStructured Text using rules described below. In either case the resulting ReStructured Text is dumped into the given file at the point where ``~dumpfile`` appears.\n\nThe ~dumpfile directive\n~~~~~~~~~~~~~~~~~~~~~~~\n\nThe ~dumpfile directive looks like this:\n\n.. code-block:: mrst\n\n ~dumpfile \"file\"
\n\n~dumpfile takes several directives by position or via keywords. The following two examples are equivalent:\n\n.. code-block:: mrst\n\n ~dumpfile \"file\" 0 10 4 ~\n\n ~dumpfile \"file\" end=10 start=0 section=~ indent=4\n\nNote that the keyword argument syntax requires no spaces between the equal sign.\n\n``start`` and ``indent`` default to 0 if not set. ``end`` defaults to the end of the file, which can also be specified explicitly using ``~``.\n\nThis next snippet means \"include all text from line 12 until the end of the file and indent everything by 4 characters:\n\n.. code-block:: mrst\n\n ~dumpfile \"file\" 12 ~ 4\n\nThis simply dumps the entire file:\n\n.. code-block:: mrst\n\n ~dumpfile \"file\"\n\nThere's also a ``section`` keyword argument, explained below.\n\n\nMarkdown Conversion\n-------------------\n\nMarkdown translation is provided courtesy of Pandoc. A subset of the desired Markdown file is generated in a temporary directory (so that `start` and `end` will work) and Pandoc is called to produce a file which is read and included where `~dumpfile` is seen.\n\nOne gotcha is that currently the section headers from Markdown docs are brought in as is, which may not work in the context of a larger rst project.\n\nFor example, you may want to dump the contents of the ``README.md`` file at the root of your git repo into your Sphinx generated documentation. However, if this file begins with a top header (such as ``# My Library``, which it almost certainly does) that will translate to a top level section header in your generated RsT project, which will probably mess up how your document is nested.\n\nThis can be avoided by simply skipping the first line (which contains the section header) by setting the ``start`` argument to 2 or more.\n\n\nC++ to ReStructured Text Conversion\n-----------------------------------\n\nThe parser reads C++ code and ignores everything until it sees special comment syntax it likes, which looks like this:\n\n.. code-block:: c++\n\n // ---------------------------------------------\n\nThe important bit is that there are two slashes, a space, and then at least two hyphens.\n\nEverything after that is included in the rst file until it sees another similar line.\n\nHere's an example:\n\n // --------------------------------------------\n // Section Header\n // ===========================================\n // This describes something important.\n // -------------------------------------------/\n\nThis gets translated to the following rst:\n\n.. code-block:: rst\n\n Section Header\n ==============\n This describes something important.\n\nNote the last C++ comment is a line full of dashes ending with ``/``: that's important. It tells the translator to stop until it sees the next comment that looks like rst.\n\nAlternatively, it's possible to make the translator scoop up actual C++ code. There's two ways to do this.\n\nThe first is to use the special directive ``// ~begin-code``. That will tell mrst to put all the code below as a C++ snippet in the rst file until it gets to ``// ~end-code``. For example:\n\n.. code-block:: c++\n\n // ~begin-code\n\n int main() {\n // this documents how you can have a signature for main like this\n // on some platforms\n }\n\n // ~end-code\n\nbecomes:\n\n.. code-block:: rst\n\n .. code-block:: c++\n\n int main() {\n // this documents how you can have a signature for main like this\n // on some platforms\n }\n\nInstead of ``// ~end-doc`` you can also just give it a comment like described above, like this:\n\n.. code-block:: c++\n\n // ------------------------------------------------------------------\n // get_customer_id\n // ------------------------------------------------------------------\n // Grabs a customer.\n // ------------------------------------------------------------------\n template\n inline int get_customer_id(Customer & c) {\n return get_id(c);\n }\n\n // ------------------------------------------------------------------\n // charge_customer\n // ------------------------------------------------------------------\n // Used to charge a customer.\n // ------------------------------------------------------------------\n void charge_customer(int c_id, double money);\n\nbecomes:\n\n.. code-block:: rst\n\n get_customer_id\n ---------------\n Grabs a customer.\n\n .. code-block:: c++\n\n template\n inline int get_customer_id(Customer & c) {\n return get_id(c);\n }\n\n charge_customer\n ---------------\n Used to charge a customer.\n\n .. code-block:: c++\n\n void charge_customer(int c_id, double money);\n\nThis behavior of treating the end of the special comment block like an ``// ~end-doc`` is to make the pattern seen above easier.\n\nIf you don't want to consume the code below a special comment, end it with ``// ---/`` as seen above.\n\n\nHere's an example of a class being included in rst:\n\n.. code-block:: c++\n\n // --------------------------------------------\n // class RenderPlatform\n // --------------------------------------------\n // A platform for renderers.\n // Note how this text will get de-dented.\n // --------------------------------------------\n\n class RenderPlatform {\n public:\n virtual ~RenderPlatform();\n virtual const char * get_name() const;\n virtual const int priority() const;\n };\n // end-doc\n\nthe above turns into:\n\n.. code-block:: rst\n\n class RenderPlatform\n --------------------\n A platform for renderers.\n Note how this text will get de-dented.\n\n.. code-block:: c++\n\n class RenderPlatform {\n public:\n virtual ~RenderPlatform();\n virtual const char * get_name() const;\n virtual const int priority() const;\n };\n\nSection headers\n~~~~~~~~~~~~~~~\n\nWhen parsing C++ files it's sometimes necessary to tell the C++ to rst generator what section header the incoming dumped rst should be nested under. The expected order of the section headers can be found in the `HEADERS` var defined in cpp_rst.py (note: Sphinx lets you use an arbitrary order, but you have to use the same order mrst uses in order to chnage the section headers found in C++ files).\n\nLet's say you want to the documentation in a header file to appear under an existing section header in your rst file. You'd do this:\n\n.. code-block:: rst\n\n namespace blah\n ~~~~~~~~~~~~~~\n\n ~dumpfile \"blah/util.hpp\" section=~\n\n\nThis would tell the C++ rst translator to start the next section after ``~``, meaning the first section header would be generated as ``^``.", "description_content_type": "", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "", "keywords": "", "license": "MIT", "maintainer": "", "maintainer_email": "", "name": "mrst", "package_url": "https://pypi.org/project/mrst/", "platform": "", "project_url": "https://pypi.org/project/mrst/", "project_urls": null, "release_url": "https://pypi.org/project/mrst/0.5.1/", "requires_dist": null, "requires_python": "", "summary": "Augments rst docs", "version": "0.5.1" }, "last_serial": 4500688, "releases": { "0.3.0": [ { "comment_text": "", "digests": { "md5": "5d158d3738d1abf1185b0b9b3d99c682", "sha256": "e7025ae97d9d8a6a294bce82583c7670f2e6561941dc899d30a176af7add44ed" }, "downloads": -1, "filename": "mrst-0.3.0.tar.gz", "has_sig": false, "md5_digest": "5d158d3738d1abf1185b0b9b3d99c682", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4751, "upload_time": "2018-05-03T04:18:22", "url": "https://files.pythonhosted.org/packages/c6/67/f173aefa857d932107d4e6c1c18459452615da9e6b9810555f7ba2ff6871/mrst-0.3.0.tar.gz" } ], "0.4.0": [ { "comment_text": "", "digests": { "md5": "ef6da10e29ef72a6d35247329311304d", "sha256": "058bfa984e9f773a81ef38d69687db468161789cae55ec386953eae4f82f542d" }, "downloads": -1, "filename": "mrst-0.4.0.tar.gz", "has_sig": false, "md5_digest": "ef6da10e29ef72a6d35247329311304d", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4816, "upload_time": "2018-05-03T05:34:37", "url": "https://files.pythonhosted.org/packages/94/d5/b11b551f25cfbc1de42ad56536a51ddc8ef98b51c416718633fb40e72065/mrst-0.4.0.tar.gz" } ], "0.4.1": [ { "comment_text": "", "digests": { "md5": "c031828fc5a6039f107e169742c69382", "sha256": "c7e30d1c3e4dbc366cacda7ec61cada4114744743773b845cc2ac342e5ed5d4c" }, "downloads": -1, "filename": "mrst-0.4.1.tar.gz", "has_sig": false, "md5_digest": "c031828fc5a6039f107e169742c69382", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4819, "upload_time": "2018-05-08T04:56:24", "url": "https://files.pythonhosted.org/packages/4b/14/ae2bf857593cb73f1da995716b8e0c7da9c6dcc794e07e41e4dfe149dd75/mrst-0.4.1.tar.gz" } ], "0.4.2": [ { "comment_text": "", "digests": { "md5": "277c33f2c01428582a0c50e784c6e120", "sha256": "c16d5ff2bd6805377a9e0bd927bd28ce61fe66f004239f57dbf5cbd6a7d84786" }, "downloads": -1, "filename": "mrst-0.4.2.tar.gz", "has_sig": false, "md5_digest": "277c33f2c01428582a0c50e784c6e120", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4817, "upload_time": "2018-05-08T05:35:27", "url": "https://files.pythonhosted.org/packages/48/43/924651513a050eb934cf2141b4b0d88f83589b2c33f37dff62d7da72c4fb/mrst-0.4.2.tar.gz" } ], "0.5.0": [ { "comment_text": "", "digests": { "md5": "dbfb511e4da25d1e5c121ee062154634", "sha256": "6eeedb6a2e125825d35048b2180a5c7897e67d00d71defc69aee50244383f4a1" }, "downloads": -1, "filename": "mrst-0.5.0.tar.gz", "has_sig": false, "md5_digest": "dbfb511e4da25d1e5c121ee062154634", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13168, "upload_time": "2018-11-18T20:50:37", "url": "https://files.pythonhosted.org/packages/c1/06/c954a5cfb6ff581abec28bdb99f376bf2a180f919543cf19ed9b99238e64/mrst-0.5.0.tar.gz" } ], "0.5.1": [ { "comment_text": "", "digests": { "md5": "30b303f89790ca85c1c7060eada2ccef", "sha256": "a9ccf476d4c94b7ae04d5a018c750b8f4acc7f2f02451b9078e6cfd7b85f6e41" }, "downloads": -1, "filename": "mrst-0.5.1.tar.gz", "has_sig": false, "md5_digest": "30b303f89790ca85c1c7060eada2ccef", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13135, "upload_time": "2018-11-18T20:55:28", "url": "https://files.pythonhosted.org/packages/bf/88/bb897fcf3c9f55f0f0f3d0e523bdcb165a6345223b4b52afe20b2f5fe31c/mrst-0.5.1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "30b303f89790ca85c1c7060eada2ccef", "sha256": "a9ccf476d4c94b7ae04d5a018c750b8f4acc7f2f02451b9078e6cfd7b85f6e41" }, "downloads": -1, "filename": "mrst-0.5.1.tar.gz", "has_sig": false, "md5_digest": "30b303f89790ca85c1c7060eada2ccef", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13135, "upload_time": "2018-11-18T20:55:28", "url": "https://files.pythonhosted.org/packages/bf/88/bb897fcf3c9f55f0f0f3d0e523bdcb165a6345223b4b52afe20b2f5fe31c/mrst-0.5.1.tar.gz" } ] }