make docs build successfully , activate dochack

[Vindaar]

I'm trying to fix the docs such that they are created successfully on a fresh arraymancer clone.

I made a rough PR for nimcuda to fix those docs so that it's not required anymore to delete those doc comments.

Finally fixed a few things in arraymancer's own docs, which apparently aren't compliant with rst.

I'm currently trying to get dochack.js to work on the docs, but so far I'm not really successful. I've asked @kaushalmodi, he got it working on his repos.
For some reason for arraymancer the inclusion of the dochack.js script in the HTML simply doesn't appear. I'll try to figure it out.

Update:

I managed to figure out what the problem was. I wasn't aware of the existence of nimdoc.cfg and didn't realize arraymancer provided its own file, which explicitly did not include the dochack.js.

nimdoc.cfg

I've written some code that generates the nimdoc.cfg for us. The reason we might want that is because it avoids breaking links in the header of the documentation. We only generate those links, which point to existing files (tensor.comparison, Reshape & Flatten and maybe others are broken, because the files don't exist anymore).

This code includes a mapping from HTML filenames to nice names, which show up in the header. I still have to fix some names I believe though.

building the docs

The whole documentation is now generated by one proc - buildDocs - which is derived from @genotrance's nimterop code here:

https://github.com/nimterop/nimterop/blob/master/nimterop/docs.nim

Except in our case we compile first build a sequence of all Nim filenames (except those from a set of excluded directories and files) and then create the docs for each.

Currently I don't exclude any directories. If that's desired, you can add them here:

https://github.com/Vindaar/Arraymancer/blob/fixDocs/docs/docs.nim#L50-L52

The structure of the docs is completely flattened (same as for Nim's own documentation). This allows for easier injection of the dochack.js without having to change the HTML code to generate for each subdirectory.

I added two sets, which track the processed files and duplicates and echo a warning, if duplicate filenames in the project are found (and thus one overrides the other). There's more than one openmp.nim apparently.

Locally for me everything works now. All links are clickable and work (including import links). I can't test the dochack though. But I don't know why it wouldn't work, once it's pushed.

Finally, I left the old arraymancer css. This means the dark mode button is there, but only affects a couple of css items, which are actually used in this.

I'm not sure if you @mratsim want to keep using that or switch to Nim's default (with support for a dark mode).

[Vindaar]

Ok, I consider this mostly done now (unless it again fails the CI..).

I introduced automatic scrolling for the header, since it's so large for some columns (and now even larger than before).

Mainly I think you'll have to check out the branch yourself and see

1. if you like it
2. if some more files / directories should be dropped or renamed in the header.

Also I can't push the docs anyways. :)

[mratsim]

The last one was another symptom of nimble unexpectedly dropping the directory structure on install and forcing dev to use hacks:

• [RFC] Nim package structure (library author point-of-view) nim-lang/nimble#472
• Frictionless Nimble directory structures nim-lang/nimble#653
• Nimble package structure RFC nim-lang/Nim#6700

Even nimble needed to use a hack around this src:

https://github.com/nim-lang/nimble/blob/b629048249ae63117ff90a813037dccab2965983/nimble.nimble#L4-L9