Generate diagrams for the application

[pmoura]

I cannot do this myself yet as I'm still missing the correct version of the serd dependency on my macOS laptop. But you may have fun generating diagrams for the application.

First, start Logtalk using either the swilgt script or the pack:

?- pack_install(logtalk).
...

?- use_module(library(logtalk)).
...

Then, load the application and try the next queries:

?- [start].
...

?- {diagrams(loader)}.
...

?- working_directory(TerminusDB, TerminusDB),
   file_search_path(swi, SWIHome),
   atom_concat(SWIHome, '/library', Library),
   git_hash(Hash, []),
   atomic_list_concat(['https://github.com/terminusdb/terminus-server/tree/',Hash,'/'], Git),
   diagrams::rdirectory(
       terminusdb,
       '.',
       [
           zoom(true),
           path_url_prefixes(TerminusDB, Git, ''),
           path_url_prefixes(Library, 'https://github.com/SWI-Prolog/swipl-devel/tree/master/library/', ''),
           omit_path_prefixes([TerminusDB, Library]),
           title('TerminusDB'),
           layout(top_to_bottom)
        ]
   ).

The last query assumes that [start] loads all the application files. If that's not the case, load any missing files first.

[GavinMendelGleason]

Brilliant. I'll give it a go. We'll be getting rid of the serd dependency as soon as we can. Hopefully within the next month.

[pmoura]

Forgot a step. After the queries, exit Prolog and type:

$ lgt2svg

If you used the pack to load Logtalk, you will likely need to dig the path to the lgt2svg script. In my case, it's stored at ~/lib/swipl/pack/logtalk/logtalk-3.30.0/tools/diagrams/lgt2svg.sh. Requires a recent Graphviz installation.

[pmoura]

With my recent work on GitHub actions and workflows for Logtalk and Prolog repos, if you enable actions tab in this repo settings, I'm happy to submit a PR with a workflow that will (re)generate and publish the diagrams automatically on push events.

[rrooij]

@pmoura We got rid of the serd and hdt dependency in the dev branch, so might be easier for you to work with now.

[pmoura]

Great! But the required terminus_store_prolog pack cannot currently be installed on macOS (which I'm using). I'm looking into this issue first.

[pmoura]

Can you create a gh-pages branch and then go into the repo settings and set GitHub Pages to build from this branch? That will allow the diagrams to be published and browsed without disturbing anything.

[pmoura]

Meanwhile I have upload the diagrams for the dev branch at 6e079ec to:

https://logtalk.org/files/terminus-server-diagrams/

There are two sets of diagrams:

• directory and file diagrams
• entity and xref diagrams

All diagrams are linked to the source code. The zoom icon allows looking into a sub-diagram with details (e.g. going from directory to its files or from a module interface to its xref details). Most nodes and edges have live links to the directory, files, and file lines in the GitHub repos. Some entry points are:

• https://logtalk.org/files/terminus-server-diagrams/terminus_server_directory_load_diagram.svg
• https://logtalk.org/files/terminus-server-diagrams/terminus_server_directory_dependency_diagram.svg
• https://logtalk.org/files/terminus-server-diagrams/terminus_server_entity_diagram.svg
• https://logtalk.org/files/terminus-server-diagrams/terminus_server_xref_diagram.svg

The diagrams were generated using the query:

logtalk_load(diagrams(loader),
working_directory(TerminusStore,TerminusStore), getenv('HOME', Home), file_search_path(swi, SWIHome),
     atom_concat(SWIHome, '/library', Library),
     atom_concat(SWIHome, '/library/http', SWIhttp),
     atom_concat(SWIHome, '/library/pldoc', SWIpldoc),
     atom_concat(SWIHome, '/library/semweb', SWIsemweb),
     git_hash(Hash, []),
     atomic_list_concat(['https://github.com/terminusdb/terminus-server/tree/',Hash,'/'], Git),
     diagrams::rdirectory(terminus_server, '.', [
         title('terminus-server - open source model driven graph database for knowledge graph representation'),
        zoom(true),
        path_url_prefixes(TerminusStore, Git, ''),
        path_url_prefixes(SWIhttp, 'https://github.com/SWI-Prolog/packages-http/tree/master/', ''),
        path_url_prefixes(SWIpldoc, 'https://github.com/SWI-Prolog/packages-pldoc/tree/master/', ''),
        path_url_prefixes(SWIsemweb, 'https://github.com/SWI-Prolog/packages-semweb/tree/master/', ''),
        path_url_prefixes(Library, 'https://github.com/SWI-Prolog/swipl-devel/tree/master/library/', ''),
        omit_path_prefixes([TerminusStore, SWIhttp, SWIpldoc, SWIsemweb, Library, Home]),
        directory_paths(true),
        exclude_directories([examples, storage, 'terminus-schema', 'terminus-server-diagrams', tmp, utils]),
        layout(top_to_bottom)
    ]).

The query is run after loading a modified start.pl file where the single change is in its first line:

#!/usr/bin/env swilgt

[rrooij]

@pmoura Thanks a lot for the nice diagrams, they look great! I especially like the xref diagram as a quick way of showing people the current architecture.

[pmoura]

As you noticed, the nodes and edges URLs link to exact locations in the source code at GitHub. That works by linking to a specific commit (as you can see in the query above that generates the diagrams). As a consequence, the locations will become invalid as new commits are pushed. But it's easy to define an automatic workflow that updates the diagrams everytime a commit is pushed (e.g. to the dev branch) and that publishes the diagrams (e.g. to the gh-pages if you're not using it so that you can browse the diagrams at https://terminusdb.github.io/terminus-server/. Let me know if you want me to submit a pull request with the workflow (it uses GitHub actions and thus you'll need to enable both GitHub Actions and GitHub Pages in the repo settings).

[matko]

Closing due to age of issue.