[DOC] add various documentation improvements (#680)

Asciidoctor/html docs - review supported browser list - include favicon in html docs - add missing documentation about already supported start events for Event Sub-Process Contributors - better asciidoctor file display on GitHub - BPMN support how-to: document how to credit the icons taken from external sources
process-analytics · Oct 1, 2020 · a6df58e · a6df58e
1 parent 1abac6c
commit a6df58e
Show file tree

Hide file tree

Showing 7 changed files with 57 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -48,10 +48,10 @@ If you need BPMN examples, you can use resources from
 
 | <img src="https://www.google.com/chrome/static/images/chrome-logo.svg" alt="Chrome" width="18px" height="18px" /> Chrome | <img src="https://user-media-prod-cdn.itsre-sumo.mozilla.net/uploads/products/2020-04-14-08-36-13-8dda6f.png" alt="Firefox" width="18px" height="18px" /> Firefox | <img src="https://developer.apple.com/assets/elements/icons/safari/safari-96x96.png" alt="Safari" width="18px" height="18px" /> Safari | <img src="https://avatars0.githubusercontent.com/u/11354582?s=200&v=4" alt="Edge" width="18px" height="18px" /> Edge |
 | :---------: | :---------: | :---------: | :---------: |
-| Yes | Yes | Yes | Yes |
+|  :heavy_check_mark: |  :heavy_check_mark: |  :heavy_check_mark: |  :heavy_check_mark: |
 
 **Note**: Internet Explorer will never be supported. \
-The library may work with the other browsers, currently not list, if they support ES6.
+The library may work with the other browsers. They must at least support ES6.
 
 ## 🎨 Features
 

diff --git a/docs/architecture/development.adoc b/docs/architecture/development.adoc
@@ -1,5 +1,12 @@
 === Development
 :icons: font
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
 
 [TIP]
 ====

diff --git a/docs/bpmn-support.adoc b/docs/bpmn-support.adoc
@@ -1,7 +1,13 @@
 [[supported-bpmn-elements]]
-
 == Supported BPMN Elements
 :icons: font
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
 
 NOTE: The BPMN support roadmap is available in https://github.com/process-analytics/bpmn-visualization-js/milestones[Github milestones]
 
@@ -163,20 +169,36 @@ The event definition can be defined on the event or on the definitions.
 |The stroke & icon width may be adjusted
 |===
 
+
 [cols="1,1,4", options="header"]
 .Event Sub-Process Interrupting Start Events
 |===
 |Name
 |Rendering
 |Comments
 
+|Timer Interrupting Start Event
+|icon:check-circle-o[]
+|The icon width may be adjusted
+
+|Message Interrupting Start Event
+|icon:check-circle-o[]
+|The stroke & icon width may be adjusted
+
+|Error Interrupting Start Event
+|icon:check-circle-o[]
+|The stroke & icon width may be adjusted
+
+|Signal Interrupting Start Event
+|icon:check-circle-o[]
+|The stroke & icon width may be adjusted
+
 |Compensation Interrupting Start Event
 |
 |
 |===
 
 
-
 [cols="1,1,4", options="header"]
 .Event Sub-Process Non-Interrupting Start Events
 |===
@@ -188,7 +210,7 @@ The event definition can be defined on the event or on the definitions.
 |icon:check-circle-o[]
 |The icon width may be adjusted
 
-|MessageNon-interrupting  Start Event
+|Message Non-interrupting Start Event
 |icon:check-circle-o[]
 |The stroke & icon width may be adjusted
 
@@ -197,6 +219,7 @@ The event definition can be defined on the event or on the definitions.
 |The stroke & icon width may be adjusted
 |===
 
+
 [cols="1,1,4", options="header"]
 .Intermediate Catch Events
 |===

diff --git a/docs/development/bpmn-support-how-to.md b/docs/development/bpmn-support-how-to.md
@@ -96,7 +96,7 @@ flow` support (see `ShapeBpmnElementKind` for more details)
 Overview of tasks to be achieved:
 - use the final icon chosen for the BPMN Elements.
 - add/update visual tests
-- update the BPMN support documentation
+- update the BPMN support documentation (see also [icons license](#icons-license))
 
 Refer to existing Pull Requests to have a better view about the work to do, for instance:
 - [Error Event Rendering Pull Request](https://github.com/process-analytics/bpmn-visualization-js/pull/505/files)
@@ -121,3 +121,14 @@ a Java tool that will let you transform your SVG file into a set of `TypeScript`
 
 Please be aware that the tool is not able to support all SVG files, and you may need to adapt the SVG definition prior the
 tool can transform it. See [PR #210](https://github.com/process-analytics/bpmn-visualization-js/pull/210) for instance.
+
+
+#### <a name="icons-license"></a> Reusing existing icons
+
+If you integrate icons that you have not designed by yourself, please don't forget to credit its author and reproduction
+conditions. Please try to use materials covered by a Free License to avoid any license compliance issues.
+
+In that case, you must add credit in the following docs: 
+- in the source code
+- in the BPMN support documentation: at the same place or close to the BPMN supported element 
+- in the main README: we don't list all icons there, but we reference projects where the icons come from
diff --git a/docs/index.adoc b/docs/index.adoc
@@ -15,6 +15,8 @@
 :sectlinks:
 // number parts of a book
 :partnums:
+// include a link to a favicon
+:favicon:
 // enable font-awesome icons
 :icons: font
 

diff --git a/docs/intro.adoc b/docs/intro.adoc
@@ -1,4 +1,5 @@
 == Introduction
+:favicon:
 
 image::images/diagram-example.png[]
 
@@ -39,15 +40,15 @@ If you need BPMN examples, you can use resources from:
 |===
 | image:https://www.google.com/chrome/static/images/chrome-logo.svg[width=18] Chrome | image:https://user-media-prod-cdn.itsre-sumo.mozilla.net/uploads/products/2020-04-14-08-36-13-8dda6f.png[width=18] Firefox | image:https://developer.apple.com/assets/elements/icons/safari/safari-96x96.png[width=18] Safari | image:https://avatars0.githubusercontent.com/u/11354582?s=200&v=4[width=18] Edge
 
-|Yes
-|Yes
-|Yes
-|Yes
+| icon:check[]
+| icon:check[]
+| icon:check[]
+| icon:check[]
 
 |===
 
-**Note**: Internet Explorer won't never be supported. +
-The library may work with the other browsers, currently not list, if they support ES6.
+**Note**: Internet Explorer will never be supported. +
+The library may work with the other browsers. They must at least support ES6.
 
 
 == ♻️ Usage

diff --git a/scripts/docs.js b/scripts/docs.js
@@ -42,6 +42,7 @@ fse.ensureDirSync(`${docsOutput}/images`);
 
 fse.copySync('docs/images', `${docsOutput}/images`);
 fse.copySync('docs/architecture/images', `${docsOutput}/images`);
+fse.copySync('src/static/img/favicon.ico', `${docsOutput}/favicon.ico`);
 
 // eslint-disable-next-line no-console
 console.info(`Documentation is now available in ${docsOutput}`);