Nim: Split system conceptually for doc purposes

[dom96]

For common types such as string and seq it's difficult to obtain information about how to perform common operations like appending data or slicing.

Wading through the behemoth that is the system is tough, especially for a newbie.

I propose the following:

1. Split up system conceptually into the following docs:
   
   
   
   • system/seq.html
   
   
   • system/string.html
   
   
   • system/set.html
   
   
   • etc
   
   
2. Include an intro at the top of each doc, just like we're doing with @narimiran's awesome initiative (#10330)

The simplest way to implement this might be to split up the system module into separate files and include them all in system.nim, then add these separate files into the doc gen.

I think doing so will make it much easier to get started with Nim as system holds some really fundamental aspects of the stdlib and the language.

[Araq]

I'd rather split system.nim. For all purposes.

[dom96]

I would prefer that option, didn't think you'd go for it though.

In any case, what I suggest could be the first step towards that goal :) Looks like this should go into the v1 milestone ;)

[Araq]

Funny I always thought you are against it @dom96

[timotheecour]

@Araq
btw: i have a POC that helps doing that based on {.nosystem.} that also avoids include hacks and instead uses import
Although include is very useful in certain niche scenarios, in the vast majority of cases import should be used as leads to much saner modular code (and avoids pitfalls specific to include eg {.exportc.} procs, top-level doc in include bugs, or compiler re-parsing the same file etc).

Currently, {.include.} is IMO being overly abused and {.nosystem.} pragma along with splitting up system will greatly help with that aspect (in addition to other aspects)

[narimiran]

Progress so far:

• several modules are moved out of system.nim (iterators, assertions, dollars, io, widestr) and now have separate documentation
• system.nim docs now have a short overview of the most important/used functions for each type, making using system's docs easier for newcomers (and the rest of us too)

I would say this is enough for 0.20 (it is labeled for 0.20 milestone) and this can be closed.

---

Q: Why not move more things out?
A: It's not as simple as it might seem. Trust me, I'm the one who worked on moving iterators, assertions, etc.