docs: add more visibility to Custom node (mingrammer#284) (mingrammer…

…#424)

* Try to make the custom doc page (mingrammer#284)

* [Fix] link syntax

* [Fix] Generate the doc for custom outside the provider loop + Remove custom from providers list.

* [Fix] Add custom menu in side bar

* docs(Custom): Add more examples (mingrammer#284)

autogen.sh

@@ -4,7 +4,7 @@ set -e
 app_root_dir="diagrams"
 
 # NOTE: azure icon set is not latest version
-providers=("onprem" "aws" "azure" "gcp" "firebase" "k8s" "alibabacloud" "oci" "programming" "saas" "elastic" "generic" "openstack" "outscale")
+providers=("onprem" "aws" "azure" "gcp" "firebase" "k8s" "alibabacloud" "oci" "programming" "saas" "elastic" "generic" "openstack" "outscale" )
 
 if ! [ -x "$(command -v round)" ]; then
   echo 'round is not installed'
@@ -52,6 +52,10 @@ for pvd in "${providers[@]}"; do
   python -m scripts.generate "$pvd"
 done
 
+# Generate doc for custom module
+echo "generating the docs for custom"
+python -m scripts.generate "custom"
+
 # run black
 echo "linting the all the diagram modules"
 black "$app_root_dir"/**/*.py

diagrams/saas/chat.py

@@ -8,7 +8,6 @@ class _Chat(_Saas):
     _icon_dir = "resources/saas/chat"
 
 
-
 class Discord(_Chat):
     _icon = "discord.png"
 

docs/nodes/custom.md

@@ -0,0 +1,90 @@
+---
+id: custom
+title: Custom
+---
+
+## Custom with local icons
+
+For this example we use the following architecture:
+
+```
+.
+├── custom_local.py
+├── my_resources
+│   ├── cc_heart.black.png
+│   ├── cc_attribution.png
+│   ├──...
+```
+
+The content of custom_local.py file:
+
+```python
+from diagrams import Diagram, Cluster
+from diagrams.custom import Custom
+
+
+with Diagram("Custom with local icons\n Can be downloaded here: \nhttps://creativecommons.org/about/downloads/", show=False, filename="custom_local", direction="LR"):
+  cc_heart = Custom("Creative Commons", "./my_resources/cc_heart.black.png")
+  cc_attribution = Custom("Credit must be given to the creator", "./my_resources/cc_attribution.png")
+
+  cc_sa = Custom("Adaptations must be shared\n under the same terms", "./my_resources/cc_sa.png")
+  cc_nd = Custom("No derivatives or adaptations\n of the work are permitted", "./my_resources/cc_nd.png")
+  cc_zero = Custom("Public Domain Dedication", "./my_resources/cc_zero.png")
+
+  with Cluster("Non Commercial"):
+    non_commercial = [Custom("Y", "./my_resources/cc_nc-jp.png") - Custom("E", "./my_resources/cc_nc-eu.png") - Custom("S", "./my_resources/cc_nc.png")]
+
+  cc_heart >> cc_attribution
+  cc_heart >> non_commercial
+  cc_heart >> cc_sa
+  cc_heart >> cc_nd
+  cc_heart >> cc_zero
+```
+
+It will generate the following diagram:
+
+![custom local](/img/custom_local.png)
+
+
+## Custom with remote icons
+
+If your icons are hosted and can be accessed when you generate the diagrams, you can
+
+```python
+from diagrams import Diagram, Cluster
+from diagrams.custom import Custom
+from urllib.request import urlretrieve
+
+with Diagram("Custom with remote icons", show=False, filename="custom_remote", direction="LR"):
+
+  # download the icon image file
+  diagrams_url = "https://github.com/mingrammer/diagrams/raw/master/assets/img/diagrams.png"
+  diagrams_icon = "diagrams.png"
+  urlretrieve(diagrams_url, diagrams_icon)
+
+  diagrams = Custom("Diagrams", diagrams_icon)
+
+  with Cluster("Some Providers"):
+
+    openstack_url = "https://github.com/mingrammer/diagrams/raw/master/resources/openstack/openstack.png"
+    openstack_icon = "openstack.png"
+    urlretrieve(openstack_url, openstack_icon)
+
+    openstack = Custom("OpenStack", openstack_icon)
+
+    elastic_url = "https://github.com/mingrammer/diagrams/raw/master/resources/elastic/saas/elastic.png"
+    elastic_icon = "elastic.png"
+    urlretrieve(elastic_url, elastic_icon)
+
+    elastic = Custom("Elastic", elastic_icon)
+
+  diagrams >> openstack
+  diagrams >> elastic
+```
+
+It will generate the following diagram:
+
+![custom local](/img/custom_remote.png)
+
+
+Another example can be found [Here](https://diagrams.mingrammer.com/docs/getting-started/examples#rabbitmq-consumers-with-custom-nodes).

scripts/generate.py

@@ -2,7 +2,7 @@
 import sys
 from typing import Iterable
 
-from jinja2 import Environment, FileSystemLoader, Template
+from jinja2 import Environment, FileSystemLoader, Template, exceptions
 
 import config as cfg
 from . import app_root_dir, doc_root_dir, resource_dir, template_dir
@@ -41,7 +41,12 @@ def _gen_class_meta(path: str) -> dict:
 
 
 def gen_apidoc(pvd: str, typ_paths: dict) -> str:
-    tmpl = load_tmpl(cfg.TMPL_APIDOC)
+    try:
+      default_tmp = cfg.TMPL_APIDOC.split('.')
+      tmpl_file = f"{default_tmp[0]}_{pvd}.{default_tmp[1]}"
+      tmpl = load_tmpl(tmpl_file)
+    except exceptions.TemplateNotFound:
+      tmpl = load_tmpl(cfg.TMPL_APIDOC)
 
     # TODO: remove
     def _gen_class_name(path: str) -> str:

templates/apidoc_custom.tmpl

@@ -0,0 +1,6 @@
+---
+id: {{ pvd }}
+title: {{ pvd|up_or_title(pvd) }}
+---
+
+For a full example check: [Here](https://diagrams.mingrammer.com/docs/getting-started/examples#rabbitmq-consumers-with-custom-nodes).

website/i18n/en.json

@@ -32,6 +32,9 @@
       "nodes/azure": {
         "title": "Azure"
       },
+      "nodes/custom": {
+        "title": "Custom"
+      },
       "nodes/elastic": {
         "title": "Elastic"
       },

website/sidebars.json

@@ -24,7 +24,8 @@
       "nodes/elastic",
       "nodes/generic",
       "nodes/programming",
-      "nodes/saas"
+      "nodes/saas",
+      "nodes/custom"
     ]
   }
-}
+}