{"id":21285264,"url":"https://github.com/pedrohdz/muextensions","last_synced_at":"2025-03-15T15:12:27.852Z","repository":{"id":57443856,"uuid":"198055971","full_name":"pedrohdz/muextensions","owner":"pedrohdz","description":"Adding PlantUML and ditaa directives to reStructuredText/Docutils","archived":false,"fork":false,"pushed_at":"2019-08-25T15:26:44.000Z","size":63,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-16T09:38:52.455Z","etag":null,"topics":["ditaa","docutils","hovercraft","pelican-plugin","plantuml","restructuredtext"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pedrohdz.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-21T12:53:14.000Z","updated_at":"2019-08-25T15:26:46.000Z","dependencies_parsed_at":"2022-09-10T20:22:51.774Z","dependency_job_id":null,"html_url":"https://github.com/pedrohdz/muextensions","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pedrohdz%2Fmuextensions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pedrohdz%2Fmuextensions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pedrohdz%2Fmuextensions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pedrohdz%2Fmuextensions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pedrohdz","download_url":"https://codeload.github.com/pedrohdz/muextensions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243746200,"owners_count":20341203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ditaa","docutils","hovercraft","pelican-plugin","plantuml","restructuredtext"],"created_at":"2024-11-21T11:19:16.419Z","updated_at":"2025-03-15T15:12:27.832Z","avatar_url":"https://github.com/pedrohdz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. COMMENT_OUT\n\n|Code Climate| |Build Status| |codecov| |PyPI version|\n\n###############################################################################\nmuextensions\n###############################################################################\n\n.. contents:: Table of contents\n\n\nOverview\n===============================================================================\n*This project is still in alpha.  Expect backwards compatibility breaking\nchanges.*\n\nAdds `ditaa`_ and `PlantUML`_ directives to `reStructuredText`_, and hopefully\n`Markdown`_ in the future.  *muextensions* does this by providing plugins for\nprojects like `Hovercraft! \u003cHovercraft_\u003e`_ and `Pelican`_, and simplifies\nregistering the directives with other `Docutils`_ projects.\n\nIt allows for adding a *reStructuredText* block like the following:\n\n.. code:: rst\n\n  .. ditaa-image::\n\n      +---------------+                      /---------------------+\n      | +-----------+ |    +------------+    |+---+  +----+   /---+|\n      | | ..dita::  | +---\u003e+muextensions+---\u003e+|   +-\u003e+{io}+-\u003e +   ||\n      | |   ~~~~~~~ | |    |        {io}|    ||{d}|  +----+   |   ||\n      | |   ~~~~~~~ | |    +------------+    |+---+           +---/|\n      | +-----------+ |                      |                     |\n      |            {d}|                      |                     |\n      +---------------+                      +---------------------/\n\nAnd having it embedded in the `Docutils`_ generated document as an image:\n\n.. image:: ./docs/images/simple-ditaa-example.svg\n  :alt: Simple ditaa example\n  :align: center\n\n\nIn the case of *PlantUML*, a block like:\n\n.. code:: rst\n\n  .. plantuml-image::\n\n    skinparam monochrome true\n    skinparam shadowing false\n\n    client -\u003e front_end\n    front_end -\u003e back_end\n    back_end -\u003e front_end\n    front_end -\u003e client\n\nWould be rendered as:\n\n.. image:: ./docs/images/simple-plantuml-example.svg\n  :alt: Simple PlantUML example\n  :align: center\n\n\nUsage\n===============================================================================\n\nPrerequisites\n-------------\n\nInstall `PlantUML`_ and have a wrapper script with the name ``plantuml`` that\nexecutes it installed in your path for *PlantUML* support.  A sample wrapper\nscript is included in `contrib/scripts/plantuml \u003cplantuml_wrapper_\u003e`_ of this\nproject.\n\nFor `ditaa`_ support, install as described in the `Getting it \u003cget_ditaa_\u003e`_\nsection of the *ditaa* documentation.\n\n.. _get_ditaa: https://github.com/stathissideris/ditaa#getting-it\n.. _plantuml_wrapper: contrib/scripts/plantuml\n\n\nPelican\n-------\n\n*muextensions* provides a plugin for `Pelican`_ in\n``muextensions.contrib.pelican``.\n\nIf everything is configured correctly, integrating *muextensions* into\n*Pelican* should be as simple as:\n\n1. Installing *muextensions* in the Python virtual environment that *Pelican*\n   is installed in with:\n\n   .. code:: bash\n\n      pip install muextensions\n\n2. Appending ``'muextensions.contrib.pelican'`` to ``PLUGINS`` in your\n   ``pelicanconf.py``:\n\n   .. code:: python\n\n      PLUGINS = ['muextensions.contrib.pelican',]\n\nFor more information on how to configure plugins in *Pelican*, refer to the\n`How to use plugins \u003cpelican_plugins_\u003e`_ section in their documentation.\n\n.. _pelican_plugins: http://docs.getpelican.com/en/stable/plugins.html\n\n\nHovercraft!\n-----------\n\nSupport for `Hovercraft! \u003cHovercraft_\u003e`_ is currently pending pull request\n`regebro/hovercraft#196 \u003chovercraft_pr_196_\u003e`_\nwhich adds the ``--directive-plugin`` argument to the ``hovercraft`` command.\nThe source code introducing ``--directive-plugin`` can be found in\n`pedrohdz/hovercraft \u003cPATCHED_\u003e`_ under the ``directives`` branch.\n\nHere is a quick example to see *muextensions*, make sure to complete the\n`Prerequisites`_ first.  We will utilize the demo presentation in\n`docs/examples/hovercraft/ \u003cdocs/examples/hovercraft/\u003e`_.\n\n.. code:: bash\n\n  cd docs/examples/hovercraft/\n  python3.7 -m venv .venv\n  source .venv/bin/activate\n  pip install -U pip\n  pip install muextensions \\\n      https://github.com/pedrohdz/hovercraft/archive/directives.zip\n  hovercraft --directive-plugin muextensions.contrib.hovercraft demo.rst\n\nOpen http://localhost:8000/ in a web browser to see the *Hovercraft!*\npresentation.\n\n.. _Hovercraft: https://hovercraft.readthedocs.io/en/latest/\n.. _PATCHED: https://github.com/pedrohdz/hovercraft/tree/directives\n\n\nOther docutils projects\n-----------------------\n\nThe *muextensions* *reStructuredText* directives can be added to any\n`Docutils`_ project by way of *Docutils* *connectors* in\n``muextensions.connector.docutils``.\n\n.. code:: python\n\n  from pathlib import Path\n  from muextensions.connector.docutils import plantuml, ditaa\n\n  output_path = Path('.')\n  plantuml.register(output_path)\n  ditaa.register(output_path)\n\nThe ``plantuml`` and ``ditaa`` ``register()`` functions in\n``muextensions.connector.docutils`` handle registering the *reStructuredText*\ndirectives as described in the `Register the Directive \u003cdocutils_register_\u003e`_\nsection on the *Docutils* of the documentation.\n\n.. _docutils_register: http://docutils.sourceforge.net/docs/howto/rst-directives.html#register-the-directive\n\n.. _Docutils: http://docutils.sourceforge.net/index.html\n\n\nDevelopment\n===============================================================================\n\nSetting up for development:\n\n.. code:: bash\n\n  git clone git@github.com:pedrohdz/muextensions.git\n  cd muextensions\n  python3.5 -m venv .venv\n  source .venv/bin/activate\n  pip install -U pip\n  pip install -e .[ci,test]\n\n\nMake sure you have a good baseline by running ``tox``.  Executing ``tox`` from\nwithin a *venv* (Python virtual environments) will cause ``pip`` related errors\nduring the tests, either exit the *venv* via the ``deactivate`` command, or\nexecute ``tox`` from a new terminal.\n\n.. code:: bash\n\n  deactivate\n  tox\n  source .venv/bin/activate\n\nTo execute the unit tests:\n\n.. code:: bash\n\n  pytest\n\nTo execute and view the unit test code coverage:\n\n.. code:: bash\n\n  pytest --cov-report=html --cov\n  open htmlcov/index.html\n\nTo run the integration tests, assuming both ``ditaa`` and ``plantuml`` are\ninstalled on the system, use the ``--run-integration`` option.  To save the\noutput of the integration tests for examination, add the\n``--save-integration-output-to`` option:\n\n.. code:: bash\n\n  pytest --run-integration\n  pytest --run-integration --save-integration-output-to=./tmp\n\n\nContribution\n------------\n\nWhen contributing, please keep in mind the following before submitting the pull\nrequest:\n\n- Make sure that the ``tox`` checks complete without failure.\n- When making code changes, add relevant unit tests.\n- If fixing a bug, please try and add a regression test.  It should fail before\n  the fix is applies, and pas after.\n- This project conforms to `Semantic Versioning 2.0.0 \u003csemver_\u003e`_.\n\n.. _semver: https://semver.org/\n\n\nAppendix\n===============================================================================\n\nTodo list\n---------\n\n- [X] Add Pelican support.\n- [X] Add Ditaa support.\n- [-] Spread the word:\n\n  - [-] Try and get it listed in `getpelican/pelican-plugins\n    \u003chttps://github.com/getpelican/pelican-plugins\u003e`_\n    (`getpelican/pelican-plugins#1165\n    \u003chttps://github.com/getpelican/pelican-plugins/pull/1165\u003e`_).\n  - [-] Try and get it listed in `stathissideris/ditaa\n    \u003chttps://github.com/stathissideris/ditaa\u003e`_ (`stathissideris/ditaa#55\n    \u003chttps://github.com/stathissideris/ditaa/pull/55\u003e`_).\n\n- [-] Finish adding plugin support to Hovercraft!  (`regebro/hovercraft#196\n  \u003chovercraft_pr_196_\u003e`_).\n- [ ] Add GitHub tickets for each of the following.\n- [ ] Make *ditaa* default to *SVG*.\n- [ ] Get the sample images in ``./docs/images/`` to render on *PyPI*:\n  https://pypi.org/project/muextensions/.\n- [ ] Add caching.\n- [ ] Add a ``plantuml-text`` directive.  This should generate and embed ASCII\n  art by way of ``plantuml -ttxt``.\n- [ ] Add a ``ditaa-text`` directive.  This should embed ASCII art in the\n  directive contents directly as a ``code`` block.\n- [ ] Add ``ditaa-figure`` and ``plantuml-figure`` directives the inherit from\n  `figure\n  \u003chttp://docutils.sourceforge.net/docs/ref/rst/directives.html#figure\u003e`_.\n- [ ] Add REST callers for execs to speed things up even more.\n- [ ] Finish removing the deprecated `uml` directive.\n- [ ] Look into https://pypi.org/project/pbr/\n- [ ] Add Markdown support.\n\n\nReferences\n----------\n\n- *TODO*\n\n\n.. _reStructuredText: http://docutils.sourceforge.net/rst.html\n.. _ditaa: https://github.com/stathissideris/ditaa\n.. _PlantUML: http://plantuml.com/\n.. _Markdown: https://daringfireball.net/projects/markdown/\n.. _Hovercraft: https://hovercraft.readthedocs.io/en/latest/\n.. _Pelican: http://docs.getpelican.com/en/stable/\n\n.. _hovercraft_pr_196: https://github.com/regebro/hovercraft/pull/196\n\n.. |Code Climate| image:: https://codeclimate.com/github/codeclimate/codeclimate/badges/gpa.svg\n   :target: https://codeclimate.com/github/pedrohdz/muextensions\n.. |Build Status| image:: https://travis-ci.org/pedrohdz/muextensions.svg?branch=master\n   :target: https://travis-ci.org/pedrohdz/muextensions\n.. |codecov| image:: https://codecov.io/gh/pedrohdz/muextensions/branch/master/graph/badge.svg\n   :target: https://codecov.io/gh/pedrohdz/muextensions\n.. |PyPI version| image:: https://badge.fury.io/py/muextensions.svg\n   :target: https://badge.fury.io/py/muextensions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpedrohdz%2Fmuextensions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpedrohdz%2Fmuextensions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpedrohdz%2Fmuextensions/lists"}