JS Doc for V2

[EParisot]

Hi and thank you for this awesome lib you provide !

I wonder if you planned to add a pure JS doc ? I'm not familiar with typescript and haven't been able to compile examples to js on my machine...

Thank again !

[jacomyal]

After a discussion with @jacomyma, I think that we target an application-oriented web development audience too strongly, while there are still needs for sigma.js in more document-oriented web development. And right now, using sigma.js without a build system is not documented (and probably even not possible anyway).

Also, simply replacing TypeScript bu JavaScript in the examples will probably not solve this issue, especially since most examples are essentially JavaScript examples, with a few types annotations. For instance, this is the base template example, which is only JavaScript, except for line 9:

https://github.com/jacomyal/sigma.js/blob/90a2978a4b809485b5dffc4a2f420b044f7eba70/examples/template/index.ts#L1-L19

So, a way to solve this issue would be to release an example that loads sigma, graphology and potentially more libraries (such as graphology-gexf for instance) in a vanilla HTML webpage, with a script that loads a public graph file and displays it. This would allow users to take that example, replace the public graph file path by their own, to get something working with sigma very quickly.

I don't think going full CDN is a light enough solution, since it would require basically everything from the graphology standard library to be released on some CDN (@Yomguithereal unless it's already the case, maybe?). Maybe an alternative solution such as Skypack would fit.

[EParisot]

Hey thank you for your detailled answer ! I finally managed to use the library the way you decribed by building it locally and hosting it in my Django project as statics, I think I load graphology from external sources though, but I'm not sure anymore... This way just a few imports are needed and I can use sigma.js in my Django app, with simple JS code. Having a documentation would have been more easy, and I think a more welcoming way but looking at the library's code is a good way too ! I also had too try 1. version at first to learn basics of the library... You proposition of a detailed example seems perfect to me ! Thank you again !

[Yomguithereal]

@jacomyal I think Observables rely on bundle.run which is basically a CDN over all of npm which packs the dependencies for the browser (nevertheless it does not dedupe dependency trees, which is completely daft for Observables but that's not the point).

[xShields]

@jacomyal Hi, I would just like to further emphasize the need for a non-typescript way to run the library. I had been watching the project for a while, excited to take advantage of the webgl functionality, to try and replace some older libraries we use. Right now though, our current environment makes it unrealistic / impossible for us to try and incorporate a build system like it's expecting.

We need to be able to simply download the package(s) (CDN or otherwise), go completely offline, and reference js files in a script tag the old fashion way. Otherwise this is a bust for us unfortunately. Even if it's a heavy handed / short term solution, the alternative for us is not trying it at all.

Thank you for the continued work on the project

[Yomguithereal]

Hello @xShields,

Hi, I would just like to further emphasize the need for a non-typescript way to run the library.

What's preventing you from running the library in a non-TS environment? Sigma does not require TS to work at all.

If what you mean is that you need to forego any modern bundling system (such as webpack for instance), then static files suitable to work with script tags can be found attached to each release of the library here: https://github.com/jacomyal/sigma.js/releases and the same can be said for graphology.

[xShields]

Hi @Yomguithereal , Thanks for the quick reply

What's preventing you from running the library in a non-TS environment?

I had tried to do so previously and ran into multiple issues importing and trying to replace the minimal non-js code on line 9 of the example above

And right now, using sigma.js without a build system is not documented (and probably even not possible anyway).

Per this comment that's what lead me to believe I'm actually prevented from running w/ a non-TS environment. Is this not the case? Apologies if I'm misinterpreting something. And if so could you provide a bare-bones example, as the original request referred to? I know the requester said he was able to get it working, but that referred to loading from external sources still, and it doesn't look like an example was provided

[EParisot]

Hi @xShields , to use the library as I did, just download the released build (I use sigma.min.js version), graphology.js and graphology-library.ls (depend on your needs thought) locally. Then you can use them from local fs by a simple script import from your header. To use it :

  <head>
      <script src="sigma.min.js"></script>
      <script src="graphology.js"></script>
      <script src="graphology-library.js"></script>
  </head>

  <body>

  <div id="network"></div>

  <script>

  // get dataset
  data = JSON.parse('YOUR JSON DATA HERE');

  // setup graph
  const container = document.getElementById("network");
  const graph = new graphology.DirectedGraph();

  graph.import(data);

  const settings = {
    immutable: true,
    defaultEdgeType: 'arrow',
    defaultNodeType: 'circle',
    labelRenderedSizeThreshold: 0,
  };

  const s = new Sigma.Sigma(graph, container, settings);

  // handle events
  s.on('clickNode', e => {});

  s.refresh();

</script>

</body>

[jacomyal]

Hi @EParisot,

I released the v2.2.0 yesterday, and I fixed the import for the bundle, so that you can instantiate it using const s = new Sigma(graph, container, settings);. The other version still works though, as all exported classes are still members of the Sigma singleton.

Also, sigma.min.js is actually available on CDN.js here, and I hope graphology will be there soon as well.

Then, we will be able to add a more "plug and play" example of sigma.js, without all the building process required.

[EParisot]

Thank you this is awesome !

[xShields]

Great, thank you everyone for helping to clear this up. And thank you @EParisot for the example, appreciate it. Looking forward to testing the library

[jacomyal]

Good news, graphology is now available on CDN.js, and the following HTML code now properly works:

<!DOCTYPE html>
<html>
  <body>
    <style>
      html,
      body,
      #sigma-container {
        position: absolute;
        inset: 0;
        margin: 0;
        padding: 0;
      }
    </style>
    <div id="sigma-container"></div>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/graphology/0.20.0/graphology.umd.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/sigma.js/2.2.0/sigma.min.js"></script>
    <script>
      const container = document.getElementById("sigma-container");
      const graph = new graphology.Graph();

      graph.addNode("John", { x: 0, y: 10, size: 5, label: "John", color: "blue" });
      graph.addNode("Mary", { x: 10, y: 0, size: 3, label: "Mary", color: "red" });
      graph.addEdge("John", "Mary");

      const renderer = new Sigma(graph, container);
    </script>
  </body>
</html>

There are still some more issues to solve (how to access graphology-layout-forceatlas2 and graphology-gexf for instance), but it's still a good step.

[EParisot]

That's great thank you !

[elyobo]

Coming in and playing with the examples is very handy, but having some sort of API documentation would be useful as well if that's still on the cards - having to infer the existence of APIs from the examples or by digging into the code is not the easiest development experience as soon as you want to do something outside of the examples.

Something like what graphology provides but for Sigma would be great.

[jacomyal]

The doc will be shipped with the v3. It is implemented already, and it brings:

• A very simple HTML example on how to use sigma without TypeScript or NPM
• Various pages describing the different concepts that make sigma
• The full TypeDoc documentation

I am cleaning issues related to things that have been done already for the v3, so I close this ticket.