discussion: feasibility of adding nim-markdown in nim documentation pipeline?

[soasme]

discussion: feasibility of adding nim-markdown in nim documentation pipeline?

[soasme]

It makes sense to vender a stable version of nim-markdown into the nim repo if koch is hard to do deps mgmt. BTW, nim-markdown is implemented in builtin modules like re and strutils, so it won't cause circular dependencies issue if goes with option 1.

My questions are:

• Do you have a timeline for the work?
• Who decides when the copied source should update?
• Is the code update by sending a pull request to devel branch?

[timotheecour]

Do you have a timeline for the work?

it's pretty much a matter of doing the work (which I started as a proof of concept experiment in nim-lang/Nim#9487 ; looks promising, at least a number of RST files are converted perfectly (automatically)) ; after that, it's a matter of convincing whoever's not convinced yet that RST=>markdown transition is a good move before we can really do the transition;

it could happen quickly if the stars align but of course some convincing needs to happen.

it looks like there's a near consensus that markdown should be favored to RST, see: https://forum.nim-lang.org/t/4280 (Drop RST and join the Markdown train?)

I'd be in favor of doing it gradually, eg:

• first convert all doc/*.rst to md (dependency is less of an issue here since it's only for ./koch web)
• then figure out how to deal with RST doc comments (this could require the copying over sources option discussed above so nim doc would be able to use markdown)

Who decides when the copied source should update?

whenever we want to benefit from a newly introduced feature in a more recent version of nim-markdown
I don't think this point is a big issue, so long we have proper tests in CI

Is the code update by sending a pull request to devel branch?

ya I don't see how else it'd work

• further question: this could become tricky if nim-markdown further down the line requires dependency on other packages (unless they'd be optional); is that going to be a potential problem or no dependencies are expected to happen in the future?

[soasme]

Please go ahead. 👍

Re your further question. The answer is no. Nim-markdown aims to implement markdown based on nim standard libraries. In particular, re and strutils are the most used modules.

[soasme]

Close the issue due to inactive status. Feel free to reopen the issue if needed.