Support spring-restdocs out of the box

[ahus1]

Adding the extension's library folder is error prone for first-time-users. Users might not know about this feature if they are new to the plugin.

A notification should provide a pop-up with additional information and/or an automatic setup of the folder; for example specific to spring-boot-rest-docs as experienced by one of the plugin's users in #310

[ahus1]

Maybe pre-packaging functionality for spring-boot-rest-docs would be an idea as well (both the ruby extension plus the configuration of the necessary paths). We would need to update the ruby extension whenever the upstream project updates their ruby library.

This should work for both Maven and Gradle projects and would require a robust detection mechanism for spring-boot-rest-docs and the paths.

[luvarqpp]

But regarding this issue, it seems perfect. I have deleted .asciidoctor* file and directory and than I have started idea again. Your plugin does rendered "operation" macro as missing. After running tests (within idea), generated snippets was created and than reopenning my api.adoc file starts to render like I have set-up with custom (from spring with your fix) ruby script and custom .asciidoctorconfig file.

One more suggestion, some balloon notification for the first time of doing such magic, it would be nice to inform user that given magic is not for free, but it involved some work and support for spring restdocs in your plugin. Perhaps link to "features" documentation can be provided.

PS: I have detected some regression on 0.30.3 pre-release perhaps. It does somehow generate svg and png file for one diagram which I have as embedded plantuml diagram. If you need more info, just ask.

[ahus1]

Thank you for giving it a try. Activating the spring-restdocs macro only when the generated-snippets folder exists is a safety measure as other projects might use the same macro name for different purposes.

From the docs (for other users who might follow this issue):

When writing documentation with Spring REST Docs, the preview plugin will auto-detect the folder generated-snippets.
It looks relative to the pom.xml for target/generated-snippets or relative to build.gradle for build/generated-snippets.
Once it finds this folder, it sets the snippets attributes and enables the operation::[] block macro.

The operations macro also received auto-completion for the operations (that is: folder names in generated snippets).

Providing documentation "as you go" is something we should have for this feature. Thanks for reminding me. Trigger should be the operation::[] macro in a document. I'll link to a GitHub wiki page, and I'd be happy if you could review or co-author some content for it.

[ahus1]

Regarding the png/svg for the diagram: That's actually some build-in feature:

• regardless of what format you choose for in your source, the preview will always show png as the preview doesn't support svg well
• you can right-click on the diagram image to save it locally. You can choose from either the png or svg format as both are created during preview rendering

The diagrams should only exist in the temp folder; let me know if they appeared somewhere else and caused problems.

[ahus1]

Writing my previous comment I notice that the not only the JavaFX preview will default to PNG, but also Open-in-Browser and PDF creation. The next pre-release will fix that and use or Open-in-Browser and PDF creation the file type specified in the document.

[luvarqpp]

@ahus1 yes, it generates files (png + svg) inside my "source" directory. See screenshot.

PS: Does .asciidoctor subdirectory resides in right directory? It is not in project root...

[luvarqpp]

According autocompletion, it is genial. Thanks a lot.
Two possible improvements:

• macro could be also autocompletes (operation::)
• after hitting "enter" for last path, there should be "[]" appended at the end of line. Perhaps autocompletion for thing in bracket can be somehow added (there are six possibilities as default)

[luvarqpp]

@ahus1 according some work on documentation, I would be happy to review some and I can try to make also some PR for web. Please point me to right directory and perhaps some methodology.

[ahus1]

@luvarqpp - I was thinking about the autocomplete for the snippets in the brackets, but I'm afraid I'll do that in a separate ticket over time depending on the files present in the folder.

Autocomplete for "operation" depends on first knowing about all block macros that are available, I haven't found out how to do that yet.

Regarding the temporary images: Please switch to the JavaFX preview. While the Swing preview requires the images to be present in the current folder, I managed to redirect the file generation plus the preview to a temporary folder outside of the workspace. This is both for the images and the .asciidoctor folder.

JavaFX preview requires a 64bit Java Runtime Environment. I recommend to use the JetBrains JRE that is bundled with the IDE. Other JRE weren't that stable for the JavaFX preview.

From the README.adoc:

The most advanced and recommended preview mode (and default for new installations) is JavaFX.

To use the JavaFX preview instead of the Swing preview, you’ll need to run IntelliJ with 64bit Java and JavaFX installed. Oracle JDK installations include JavaFX, but can make the IDE unstable and crash. Pre-bundled OpenJDK installations usually don’t include JavaFX. Therefore, JetBrains OpenJDK pre-bundled with your IDE is recommended.

From 2017.1 onwards a JetBrains OpenJDK 64bit is included even in the Windows versions. Please only use the JDK provided by JetBrains, as the JavaFX rendering seems to be most stable in the JetBrains JDK. See Selecting the JDK version the IDE will run under for more details.

If you for some reason continue to use the Swing preview, I recommend to add the generated files to the .gitignore file.

[ahus1]

The latest pre-release 0.30.4 fixes the numbering issue, thanks for pointing it out. I'm sorry that I've introduced it in the latest version.

There is now also a an editor notification that links to https://github.com/asciidoctor/asciidoctor-intellij-plugin/wiki/Spring-REST-Docs-support if it suspects spring-rest-docs content.

The link takes you to the plugin's wiki page. As a logged-in GitHub user you should be able to edit the page. Feel free to post questions regarding the content in this ticket.

[ahus1]

This has been released as part of 0.30.6 as a generally available release. Please create new issue if something can be improved.