Convert Nextflow docs to markdown

[bentsherman]

After working on the Nextflow docs multiple times, I've concluded that RST is a real pain to work with. I've encountered many formatting issues that seem to result from confusion about RST syntax, as it is just different enough from markdown to be confusing.

I think we should just convert the Nextflow docs to markdown. It looks like Sphinx supports markdown and there are a number of tools to do it automatically. So the docs won't change outwardly, they will just be easier to edit (in my opinion).

[pditommaso]

That's true, however automated conversion is a myth. Once I've tried pandoc and the result was just a mess

[bentsherman]

What I've read is that some finangling might be required to get pandoc to convert correctly. Maybe I will try it myself and see how far I get.

There is also asciidoc, which we are using for some things like the nf-training and nf-patterns websites. I think I still prefer markdown, but not sure how others feel about it.

[abhi18av]

Related conversation from 2021 https://github.com/nextflow-io/nextflow/issues/2041

I do agree that RST makes it a bit tougher for new contributors to grasp, preferably markdown would be the path we opt for 🤞

Though in previous Clojure/ReactJS based projects I have worked on ASCIIDOC formatted guide as well and the overall experience was pretty straight-forward.

@jorgeaguileraseqera might have some good ideas on automated RST -> ASCIIDOC translation perhaps?

[jorgeaguileraseqera]

I think there are many projects migrating from RST to Antora (an asciidoctor toolchain to generate static sites)

We don't have a lot of files to convert so probably we can use some tool to do most part of the translation

What I don't know is if we produce also the others formats (pdf/latex ..)

[bentsherman]

I was able to convert everything to Markdown quite easily by following these instructions. Might need to tweak a few things but from a cursory inspection everything looks good. I can submit a PR for this, however we should definitely review and merge #2698 before we convert to Markdown.

[pditommaso]

Curious to see how does it render with https://github.com/squidfunk/mkdocs-material

[bentsherman]

Is that where you want to move to long term? It will probably require a second conversion step from the sphinx conventions to mkdocs conventions. Might be able to do it just with search and replace.

[pditommaso]

Likely, we are already using it for tower docs and it's a good compromise I think

[bentsherman]

Following up on the discussion with Phil and the website overhaul team, what we'd like to do for now is convert the Nextflow docs to markdown but keep the Sphinx theme.

We believe we can merge the training website, patterns, and Nextflow docs into a single site that is much more coherent and less redundant. Since that will be a huge transition by itself, better to keep the Nextflow docs looking the same until then to minimize the amount of change. After converting to markdown, the docs will look exactly the same, but will be much easier to merge with everything else.

I will draft a PR for the markdown conversion as soon as these PRs are merged: #2799 #2816 (saying this partly for myself so that I don't keep trying to work on the Nextflow docs 😆 )

[pditommaso]

Not sure what's benefits of this. I agree that markdown is more readable than RST, however, the plain version is too poor for docs.

I think this is valuable only if it provides a better docs navigation and UI

[bentsherman]

Sphinx and mkdocs-material both use an extended flavor of markdown that supports all the features used by Nextflow docs, like admonitions. For now I will convert to markdown but keep Sphinx+RTD theme, so the docs will look identical and the URLs will stay the same. Later, we will move to mkdocs-material as part of the website overhaul, which as you know supports the same kind of docs features and navigation.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[pditommaso]

Bump