ans-group/docs.ukfast.co.uk

Reproducible diagrams

Closed this issue · 10 comments

Deleted user commented

I've been looking at https://knsv.github.io/mermaid/ as a possible source to make reproducible diagrams. It comes with a plugin for sphinx - https://github.com/mgaitan/sphinxcontrib-mermaid - I think it would be good to make the diagrams reproducible since either the same person who created a diagram needs to edit it, or they need to upload the source file for others to edit. Having it programatically generated means we can keep styling consistent and have quicker iterations when changing the diagram.

I'm going to run a test and put the output here. Thinking I'll copy the diagram from https://docs.ukfast.co.uk/webcel/ssl.html for the different SSL types. If anyone has any suggestions to some other diagrams which could do with some TLC please let me know :)

garryprior commented

thanks @BenWUKFast . not sure there are too many diagrams across docs.ukfast at the moment - probably because they're not easy to produce. This tool might make it easier.

Would be interested to see how we can modify design / look & feel so as to always build diagrams in our "house style".

Deleted user commented

@garryprior Exactly, hopefully it makes the process a little easier. It produces an SVG file which can then be styled with CSS just like html can - https://knsv.github.io/mermaid/#styling

  • 👍1
nformby commented

Great idea, we can get the web team to create a stylesheet specifically for this.

Deleted user commented

@garryprior @nformby You can view an ugly diagram here - http://185.166.131.206/webcel-ssl.mmd.svg - It does have the option for vertical as well, however I felt horizontal best fit this diagram.

No css at the moment but it's easy enough to style. You can assign classes dead easily and do default classes as well if you cba setting classes for everything you want styled differently.

garryprior commented

i just get a blank screen when I hit that link?

Deleted user commented

@garryprior smash refresh a few times. Something odd happens when trying to access from our network. Just a simple python server serving the content, works perfectly from home. Always have to smash refresh a few times to get it working.

nformby commented

I've hit refresh a good 50 times and still nothing I'm afraid

Deleted user commented

Bizarre, I just uploaded it to a random host - http://svgshare.com/i/2io.svg @nformby @garryprior

Ohh and the markup which produces that:

%% Webcel SSL Types

graph LR
  httpreq[HTTPS Request]

  subgraph Passthrough
    layer4pass[L4 SSL Proxy]
  end

  subgraph Offload
    layer7offload[L7 SSL Decrypt]
    cacheoffload((Cache))
    layer7offload -.-> cacheoffload
  end

  subgraph Secure Origin Pull
    layer7op[L7 SSL SSL Decrypt]
    cacheop((Cache))
    layer7op -.-> cacheop
    layer7openc[L7 SSL Encrypt]
    cacheop -.-> layer7openc
  end

  httpreq --> layer4pass
  httpreq --> layer7offload
  httpreq --> layer7op

  asset1{Asset}

  layer4pass --> asset1
  cacheoffload -.-> asset1
  layer7openc --> asset1
nformby commented

Looks good, with a bit of CSS it should look great!