misc rst - Githubissues

timotheecour / Nim

Nim is a compiled, garbage-collected systems programming language with a design that focuses on efficiency, expressiveness, and elegance (in that order of priority).

http://nim-lang.org/

Other

2 stars 0 forks source link

misc rst #452

Open timotheecour opened 3 years ago

timotheecour commented 3 years ago

see https://github.com/nim-lang/Nim/pull/16341#issuecomment-744103319

One problem with nim's flavor of rst is it doesn't render well for those simply viewing this on github without going through any transform.

Note that https://github.com/nim-lang/Nim/blob/devel/doc/manual.rst doesn't even render well already (github doesn't interpret it correctly; unlike https://github.com/nim-lang/Nim/blob/devel/doc/intern.rst)

4 solutions:

simplest: people who care about seeing it rendered can look at https://nim-lang.github.io/Nim/manual.html, which also offers additional benefits such as search, better working links etc
improve github linguist https://github.com/github/linguist so it works well with nim's flavor of rst (or rename rst to nimrst since it's not true rst already, but github linguist only supports "popular enough" extensions)
my preferred approach was to move *.rst to *.nim (I showed it's 100% possible here: https://github.com/nim-lang/Nim/issues/14313#issuecomment-630187073, and it offers more flexiblity)
use markdown instead of rst (refs https://github.com/nim-lang/Nim/pull/9487 aimed at automating transition) but this approach has its own issues, see thread here: https://github.com/nim-lang/RFCs/issues/68

using our own flavor of rst (or md) has significant advantages when it comes to using our own tools to render it (allows more features for docgen) but comes at price of it not working so well when rendered with other tools.

timotheecour commented 3 years ago