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

[Timothee Cour]

originally asked there nim-lang/Nim#9487 but moving that specific question here:

how could we use nim-markdown for markdown=>html generation in ./koch web ? options:

• add a nimble dependency on nim-markdown for koch (is that even feasible, or would that cause circular dependencies ?)
• [preferred] copy nim-markdown sources to Nim/ tests/deps/ ; we already do this for these:
  jester-#head opengl-1.1.0 x11-1.0 zip-0.2.1

the copied sources would be (regularly) updated as needed from upstream nim-markdown (and not meant to be locally modified in Nim repo, only meant as a stale copy)

@soasme what do you think?

[Ju]

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?

[Timothee Cour]

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?

[Ju]

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.

[Ju]

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