add TOC generator to nimble file

[HugoGranstrom]

This creates a simple <ul><li> list and puts it in books/toc.mustache. Now we just have to get a layout that can read it in which is in the works at https://github.com/pietroppeter/nimib/pull/43

An example of a toc.mustache:

<ul>
<li><a href="basic_plotting.html">basic_plotting</a></li>
<li><a href="hej.html">hej</a></li>
<li><a href="tjo/tjo.html">tjo</a></li>
</ul>

[HugoGranstrom]

@Clonkk I didn't mess anything you did now, right?

[Clonkk]

entirely possible. What are you referring to ?

The CI failed once due to a network issue (relaunching the actions made it pass).

[HugoGranstrom]

@Clonkk I had to resolve a merge conflict in the Nimble file. Just wanted to check that I didn't corrupted the whole thing :)

[HugoGranstrom]

I've discovered a flaw with the links now. They are relative so if we are in folder foo and we have a link to index.html, it will take us to foo/index.html.

[HugoGranstrom]

An option would be to make all links absolute so that they work on a server. But they would work when just opening them as raw HTML files in the browser. Is that ok, or will people want to have a local copy? Perhaps they want to, but starting a simple HTTP server isn't too much of a hassle then. I'm not really sure which solution to use here 🙃

[HugoGranstrom]

Ok I think I solved it. I had to introduce a partial called path_to_home that has the current file's path to the home dir. The link is then relative to it.

[Clonkk]

Let's use html only for now. We can handle application part to serve html files using Karax either direclty in Nimib or specifically in this repo but it's not the priority for now.

[HugoGranstrom]

Too late 😛 Now it works both on servers and locally. Plus I had to create the generated toc.mustache in the docs/ folder, it wouldn't find it otherwise.

[Clonkk]

Oh, I thought you meant having a direct link to html files vs routing a function to serve the HTML .

Down the line, I believe Nimib could to use Karax to serve documentation and make it usable as a documentation server and not just an html generator (like mdbook serve).

[HugoGranstrom]

Hehe my thoughts weren't very clear so my words were even worse... I'm not really sure of the difference either. Now it (automatically) hardcodes the relative links. So if we have /index.html and /book1/part1.html the link from part1 to index is ../index.html.

Not a bad idea. 👍

[Clonkk]

Github pages already serve all the file inside the docs folder so there isn't much difference in this case (that's why I wouldn't worry about it for now)

But f we want to host the documentation elsewhere then you need an HTTP server to serve the HTML page. That's wherestuff like Karax could come in handy and where Nimib has room to grow I believe

[HugoGranstrom]

Ahh ok yes that's true 😄

Yeah you may be on to something. The more we use the Nim ecosystem the better B)

[pietroppeter]

minimal mdbook support is finally done. see example here: https://pietroppeter.github.io/nimib/book/index.html

@HugoGranstrom to adapt it to this repo you can look at the toc.mustache there. I used a {{path_to_root}} and in this way the relative links work correctly (experiment with the sample book above).

to use it you basically need to copy the complete content of docs/book folder and merge the nbPostInits.

[pietroppeter]

ah, one basic feature of the toc I am not so sure how to implement with the template is the class="active" to highlight current section of book.

[pietroppeter]

sorry, realized this book thing is too big and deserves a repo of its own. I forced the removal of last PR. I will open a new repo with this mdbook content

[pietroppeter]

and it's back alive here: https://pietroppeter.github.io/nimiBook/

I copied the structure from this repo, so it should be straightforward to port here. I could probably do it later in the weekend, but if you someone wants to go ahead and try it, feel free!

[Clonkk]

I'll take a look at it. Thanks you for doing all this work it's awesome

[HugoGranstrom]

@pietroppeter Wow it looks great! :D Only thing missing visually is a "Made with Nimib" at the bottom 😉

ah, one basic feature of the toc I am not so sure how to implement with the template is the class="active" to highlight current section of book.

I have an idea for how to solve this but it involves a bit of javascript. I'll basically loop over all links in javascript and add the class to the right element there. And I'll use mustache's text-interpolation to get all the paths. If I get it to work I'll make a PR to NimiBook (nice name btw! 😎). This is the situation when one would want if-statements in Mustache...

I'll take a look at it.

Great! Feel free to create a new PR and incorporate my changes here if you find them useful and then we'll close this one 😄

[HugoGranstrom]

Another option would be to use a lambda and use it kinda like this:

{{#parse_active}}
{{here_path}} basics/plotting.html
{{/parse_active}}

Where basics/plotting.html is the relative link inserted by the TOC generator. parse_active would then be implemented something like this:

nbDoc.context["parse_active"] =
  proc(s: string, c: Context): string =
    let rendered = s.render(c)
    let splitted = rendered.split(" ")
    if splitted[0] == splitter[1]: # we might have to adjust them so the leading `/` are the same and that both are using the same convention (/ vs \)
      return "class=\"active\""
    else:
      return ""

Does this sound sane? PR created for it now: https://github.com/pietroppeter/nimiBook/pull/1

[Clonkk]

I copied the structure from this repo, so it should be straightforward to port here. I could probably do it later in the weekend, but if you someone wants to go ahead and try it, feel free!

Great! Feel free to create a new PR and incorporate my changes here if you find them useful and then we'll close this one

I probably won't have enough time to polish a PR before next week so don't wait for me if you want to.

[pietroppeter]

@HugoGranstrom I am actually testing an approach using fixed mustache templates: see a writeupt here: https://pietroppeter.github.io/nblog/drafts/toc_mustache.html

[HugoGranstrom]

I probably won't have enough time to polish a PR before next week so don't wait for me if you want to.

I think we don't have to hurry too much here. It's more resource-effective to implement all the basic features in NimiBook first and once it's done port it over to here. Otherwise we may fall into writing the same code twice. :)