search

mikitex70 / plantuml-markdown

PlantUML plugin for Python-Markdown
BSD 2-Clause "Simplified" License
192 stars 55 forks source link

New Include Pre-processor, Theme defaulting, Enabling POST to Server and Docker Test Image #65

Closed bharatrajagopalan closed 1 year ago

bharatrajagopalan commented 2 years ago

Hi @mikitex70

Changelog below. Hopefully, I have ticked the boxes in terms of the process you require for this PR. Let me know if you need me to do anything else.

My basic use case is running this with mkdocs and a private plantuml server as part of backstage setup while getting full functionality such as !include which works with local jar

New include preprocessor for remote server

Borrowing the logic from https://github.com/quantorconsulting/mkdocs_build_plantuml where !include statements are recursively converted to plantuml text and merged into one big file to be sent to the server so that this behaves just like the local jar version (currently this just fails)

Over and above the logic taken from mkdocs_build_plantuml, the include pre-processor also parses lines ensuring that @startuml and @enduml from included files are removed and only are attached to the beginning and end of the total payload sent to the server.

POST method support

With the new include preprocessor, there is the danger that the plantuml url for get requests can get too large and hence there is also the option to turn on POST method if the plantuml server supports it. The official one doesn't support POST so I spun up a private server to test this along with mkdocs-markdown.

This also includes fallback to GET if POST fails - this basically checks the error code back from POST and anything that is not ok (400 or higher) is attempted with GET. Note that this doesn't work with plantuml.com as they actually respond to POST with a 200 code but just send regular HTML page back. But works just fine with a private server.

The other interesting bit I noted was that POST is stricter than GET e.g. it mandates the @startuml and @enduml tags.

Default theme support

Essentially you can specifiy a default theme using theme as part of config which internally attaches the !theme directive at the beginning of the file. Since the theme command can result in errors when used with specific plantuml commands - there is a configurable exception list puml_notheme_cmdlist also setup

Dockerfile for testing

I had trouble running the tests on my local due to dependencies, so I basically took the travis file already in theand used it to create a docker test image which has all the dependencies based on python alpine to ensure that the size remained small. I don't have access to travis ci (not free since 2020 unfortunately).

Test output

Starting plantuml-markdown ... done
Attaching to plantuml-markdown
plantuml-markdown    | skipped Base class
plantuml-markdown    | test_admonition (test.test_plantuml_fenced.PlantumlTest_fenced) ... ok
plantuml-markdown    | test_arg_alt (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the alt argument ... ok
plantuml-markdown    | test_arg_alt_characters (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the alt argument with special characters ... ok
plantuml-markdown    | test_arg_alt_inline_svg (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for setting alt attribute in inline SVG ... ok
plantuml-markdown    | test_arg_classes (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the classes argument ... ok
plantuml-markdown    | test_arg_classes_inline_svg (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for setting class attribute in inline SVG ... ok
plantuml-markdown    | test_arg_format_height_svg_inline (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a svg image ... ok
plantuml-markdown    | test_arg_format_png (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a png image ... ok
plantuml-markdown    | test_arg_format_svg (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a svg image ... ok
plantuml-markdown    | test_arg_format_svg_inline (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a svg image ... ok
plantuml-markdown    | test_arg_format_svg_object (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a svg image ... ok
plantuml-markdown    | test_arg_format_txt (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a txt image ... ok
plantuml-markdown    | test_arg_format_width_and_height_svg_inline (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a svg image ... ok
plantuml-markdown    | test_arg_format_width_svg_inline (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a svg image ... ok
plantuml-markdown    | test_arg_height (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the width argument ... ok
plantuml-markdown    | test_arg_height_percent (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the width argument ... ok
plantuml-markdown    | test_arg_source (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the source argument ... ok
plantuml-markdown    | test_arg_title (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the title argument ... ok
plantuml-markdown    | test_arg_title_characters (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the title argument with special characters ... ok
plantuml-markdown    | test_arg_title_inline_svg (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for setting title attribute in inline SVG ... ok
plantuml-markdown    | test_arg_width (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the width argument ... ok
plantuml-markdown    | test_arg_width_and_height (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the width and height arguments ... ok
plantuml-markdown    | test_arg_with_percent (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the correct parsing of the width argument ... ok
plantuml-markdown    | test_diagram_in_fenced_code (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Diagrams inside fenced code must not be touched ... ok
plantuml-markdown    | test_extended_header (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test the extended syntax header ... ok
plantuml-markdown    | test_indented_fenced_code (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test handling of indented fenced code ... ok
plantuml-markdown    | test_json (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test that we can use startjson and similar tags to change diagram kind ... ok
plantuml-markdown    | test_multidiagram (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test for the definition of multiple diagrams on the same document ... ok
plantuml-markdown    | test_multiple_fences (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test multiple fences in document. ... ok
plantuml-markdown    | test_other_fenced_code (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test the coexistence of diagrams and other fenced code ... ok
plantuml-markdown    | test_plantuml (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test the support of 'plantuml' language ... ok
plantuml-markdown    | test_plantuml_map (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test map markup is generated for plantuml with links ... ok
plantuml-markdown    | test_priority_after_snippets (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Verifies the normal priority of the plantuml_markdown plugin: it must be execute before the fenced code ... ok
plantuml-markdown    | test_priority_before_snippets (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Verifies changing plugin priority: in must be execute even before the snippets plugin. ... ok
plantuml-markdown    | test_source (test.test_plantuml_fenced.PlantumlTest_fenced) ... ok
plantuml-markdown    | test_tildes (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | Test correct parsing with tilde fenced block delimiter ... ok
plantuml-markdown    | test_unicode_chars (test.test_plantuml_fenced.PlantumlTest_fenced)
plantuml-markdown    | indented_code ... ok
plantuml-markdown    | skipped Base class
plantuml-markdown    | test_admonition (test.test_plantuml_legacy.PlantumlTest_legacy) ... ok
plantuml-markdown    | test_arg_alt (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the alt argument ... ok
plantuml-markdown    | test_arg_alt_characters (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the alt argument with special characters ... ok
plantuml-markdown    | test_arg_alt_inline_svg (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for setting alt attribute in inline SVG ... ok
plantuml-markdown    | test_arg_classes (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the classes argument ... ok
plantuml-markdown    | test_arg_classes_inline_svg (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for setting class attribute in inline SVG ... ok
plantuml-markdown    | test_arg_format_height_svg_inline (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a svg image ... ok
plantuml-markdown    | test_arg_format_png (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a png image ... ok
plantuml-markdown    | test_arg_format_svg (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a svg image ... ok
plantuml-markdown    | test_arg_format_svg_inline (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a svg image ... ok
plantuml-markdown    | test_arg_format_svg_object (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a svg image ... ok
plantuml-markdown    | test_arg_format_txt (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a txt image ... ok
plantuml-markdown    | test_arg_format_width_and_height_svg_inline (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a svg image ... ok
plantuml-markdown    | test_arg_format_width_svg_inline (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the format argument, generating a svg image ... ok
plantuml-markdown    | test_arg_height (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the width argument ... ok
plantuml-markdown    | test_arg_height_percent (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the width argument ... ok
plantuml-markdown    | test_arg_source (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the source argument ... ok
plantuml-markdown    | test_arg_title (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the title argument ... ok
plantuml-markdown    | test_arg_title_characters (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the title argument with special characters ... ok
plantuml-markdown    | test_arg_title_inline_svg (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for setting title attribute in inline SVG ... ok
plantuml-markdown    | test_arg_width (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the width argument ... ok
plantuml-markdown    | test_arg_width_and_height (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the width and height arguments ... ok
plantuml-markdown    | test_arg_with_percent (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the correct parsing of the width argument ... ok
plantuml-markdown    | test_diagram_in_fenced_code (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Diagrams inside fenced code must not be touched ... ok
plantuml-markdown    | test_indented_fenced_code (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test handling of indented fenced code ... ok
plantuml-markdown    | test_json (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test that we can use startjson and similar tags to change diagram kind ... ok
plantuml-markdown    | test_multidiagram (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test for the definition of multiple diagrams on the same document ... ok
plantuml-markdown    | test_multiple_fences (test.test_plantuml_legacy.PlantumlTest_legacy) ... ok
plantuml-markdown    | test_other_fenced_code (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test the coexistence of diagrams and other fenced code ... ok
plantuml-markdown    | test_plantuml_map (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Test map markup is generated for plantuml with links ... ok
plantuml-markdown    | test_priority_after_snippets (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Verifies the normal priority of the plantuml_markdown plugin: it must be execute before the fenced code ... ok
plantuml-markdown    | test_priority_before_snippets (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | Verifies changing plugin priority: in must be execute even before the snippets plugin. ... ok
plantuml-markdown    | test_source (test.test_plantuml_legacy.PlantumlTest_legacy) ... ok
plantuml-markdown    | test_unicode_chars (test.test_plantuml_legacy.PlantumlTest_legacy)
plantuml-markdown    | indented_code ... ok
plantuml-markdown    | skipped Base class
plantuml-markdown    | 
plantuml-markdown    | ----------------------------------------------------------------------
plantuml-markdown    | Ran 71 tests in 106.456s
plantuml-markdown    | 
plantuml-markdown    | OK (skipped=3)
plantuml-markdown exited with code 0
mikitex70 commented 1 year ago

Hi @bharatrajagopalan, thanks for your PR. It's now merged in the develop branch. I've done some fixes in tests and small refactors / cleanups in the code (PEP warnings, splitting big methods, etc.). Take a look if seems ok for you.

bharatrajagopalan commented 1 year ago

Thanks @mikitex70 ! Any view on when this gets released formally as part of the plugin?