Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

The route /graph_guide does not respect the HTML format described in the documentation #54

Open
ggrossetie opened this issue Sep 23, 2021 · 1 comment
Open

The route /graph_guide does not respect the HTML format described in the documentation #54

ggrossetie opened this issue Sep 23, 2021 · 1 comment
Labels
bug Something isn't working

Comments

@ggrossetie
Copy link
Collaborator

Documentation : https://github.com/neo4j-contrib/neo4j-guides/blob/master/docs/html-guides.adoc

You can take a look at:

:play https://guides.neo4j.com/graph-examples/northwind-recommendation-engine/graph_guide

It looks like the rendering is broken (i.e. the sections).
For reference, here's what we generate today for the following content:

Recently, I was asked to pitch a method for providing recommendations.  Luckily, armed with the knowledge obtained from talks from Max De Marzi and https://skillsmatter.com/skillscasts/7298-modelling-a-recommendation-engine-a-worked-example[Mark Needham^] at a recent  Neo4j London Meetups, I knew this could be easily achieved with Neo4j.

The key issue with recommendation engines comes from the data.
Luckily, Neo4j comes bundled with the Northwind Graph Example.
The Northwind database is an infamous dataset containing purchase history that has been used to teach relational databases for years and was a great place to start.

You can import the Northwind database into a graph by following the http://neo4j.com/developer/guide-importing-data-and-etl/["Import Data into Neo4j"^] post on Neo4j or type the following into Neo4j's browser, e.g. empty database in Neo4j Desktop or a https://neo4j.com/sandbox[blank sandbox^].

----
:play northwind graph
----
<html>
<body>
<!-- ... -->
<slide class="row-fluid">
  <div class="col-sm-12">
    <h3></h3>
    <br>
    <h3>Recently, I was asked to pitch a method for providing recommendations. Luckily, armed with the knowledge obtained from talks from Max De Marzi and <a
      href="https://skillsmatter.com/skillscasts/7298-modelling-a-recommendation-engine-a-worked-example" target="_blank" rel="noopener">Mark Needham</a> at a recent Neo4j London
      Meetups, I knew this could be easily achieved with Neo4j.</h3>
    <br>
  </div>
</slide>
<slide class="row-fluid">
  <div class="col-sm-12">
    <h3></h3>
    <br>
    <h3>The key issue with recommendation engines comes from the data.
      Luckily, Neo4j comes bundled with the Northwind Graph Example.
      The Northwind database is an infamous dataset containing purchase history that has been used to teach relational databases for years and was a great place to start.</h3>
    <br>
  </div>
</slide>
<slide class="row-fluid">
  <div class="col-sm-12">
    <h3></h3>
    <br>
    <h3>
      You can import the Northwind database into a graph by following the 
      <a href="http://neo4j.com/developer/guide-importing-data-and-etl/" target="_blank" rel="noopener">"Import Data into Neo4j"</a> post on Neo4j 
      or type the following into Neo4j’s browser, e.g. empty database in Neo4j Desktop or a <a href="https://neo4j.com/sandbox" target="_blank" rel="noopener">blank sandbox</a>.
    </h3>
    <br>
  </div>
</slide>
<slide class="row-fluid">
  <div class="col-sm-12">
    <h3></h3>
    <br>
    <div>:play northwind graph</div>
    <br>
  </div>
</slide>
<!-- ... -->
</body>
</html>

According to the documentation, we should instead generate something like:

<html>
<body>
<slide class="row-fluid">
  <div class="col-sm-12">
    <p>
      Recently, I was asked to pitch a method for providing recommendations. Luckily, armed with the knowledge obtained from talks from Max De Marzi and <a
      href="https://skillsmatter.com/skillscasts/7298-modelling-a-recommendation-engine-a-worked-example" target="_blank" rel="noopener">Mark Needham</a> at a recent Neo4j London
      Meetups, I knew this could be easily achieved with Neo4j.
    </p>
  </div>
</slide>
<slide class="row-fluid">
  <div class="col-sm-12">
    <p>
      The key issue with recommendation engines comes from the data.
      Luckily, Neo4j comes bundled with the Northwind Graph Example.
      The Northwind database is an infamous dataset containing purchase history that has been used to teach relational databases for years and was a great place to start.
    </p>
  </div>
</slide>
<slide class="row-fluid">
  <div class="col-sm-12">
    <p>
      You can import the Northwind database into a graph by following the
      <a href="http://neo4j.com/developer/guide-importing-data-and-etl/" target="_blank" rel="noopener">"Import Data into Neo4j"</a> post on Neo4j 
      or type the following into Neo4j’s browser, e.g. empty database in Neo4j Desktop or a <a href="https://neo4j.com/sandbox" target="_blank" rel="noopener">blank sandbox</a>.
    </p>
  </div>
</slide>
<slide class="row-fluid">
  <div class="col-sm-12">
    <figure>
      <pre class="pre-scrollable code runnable">:play northwind graph</pre>
    </figure>
  </div>
</slide>
</body>
</html>
@ggrossetie ggrossetie added the bug Something isn't working label Sep 23, 2021
@ggrossetie
Copy link
Collaborator Author

This is mostly related to the fact that some graph gists are not using a proper AsciiDoc document structure.

Let's take an example:

This is a paragraph.

This is another paragraph.

This is yet another paragraph.

----
:play northwind graph
----

Now let's get started.

== Dataset

As you can see...

The above AsciiDoc document will produce the following (simplified) Abstract Syntax Tree:

{
  "type": "document",
  "blocks": [
    {
      "type": "paragraph"
    },
    {
      "type": "paragraph"
    },
    {
      "type": "paragraph"
    },
    {
      "type": "listing"
    },
    {
      "type": "paragraph"
    },
    {
      "type": "section",
      "blocks": [
        {
          "type": "paragraph"
        }
      ]
    }
  ]
}

Here, we need to decide when we should create a new slide. Should we create a new slide for each block? should we create one slide for everything that isn't contained in a section?

In order to get a proper document structure, we need to add a document title.
Once this is done, everything before the first section is a "preamble":

{
  "type": "document",
  "blocks": [
    {
      "type": "preamble",
      "blocks": [
        {
          "type": "paragraph"
        },
        {
          "type": "paragraph"
        },
        {
          "type": "paragraph"
        },
        {
          "type": "listing"
        },
        {
          "type": "paragraph"
        }
      ]
    },
    {
      "type": "section",
      "blocks": [
        {
          "type": "paragraph"
        }
      ]
    }
  ]
}

As you can see, we now have two "top-level" blocks, one preamble and one section. In this case, we can create one slide for the preamble and one slide for the section.

To address this issue, we could mandate a proper document structure when a new graph gist is submitted and/or we could improve the template to handle more cases.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bug Something isn't working
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@ggrossetie