Migrate .rst files to .md in our docs/

KevinMind commented 9 months ago

Describe the problem and steps to reproduce it:

Convert our restructured markup to markdown syntax. Following this guide

Anything else we should know?

Migrating to using markdown will have several advantages.

it is a more popular language
It is a simpler language
It will render in github preview pages in the browser (not useful for everyone but nice to have)

There are a few downsides

We may not be able to support all of the content formats we had in restructured as markdown does not support everything. See here for more details.
It will require work to refactor the source .rst files to mardown (luckily there is a tool for at least partially automating this.

┆Issue is synchronized with this Jira Task

eviljeff commented 9 months ago

Most of our docs are documenting the API request and response so if those are readable (or can be reformatted to be readable) then we're pretty much there, imo.

KevinMind commented 8 months ago

@eviljeff I'm not sure I understand the A -> B of your comment. Are you suggesting that they are readable currently, and may not be with .md files? Or that they are not and would need to be made so? OR something totally different?

FYI I have another PR for adding swagger json/ui which may in fact make a lot of those docs obsolete .

eviljeff commented 8 months ago

@eviljeff I'm not sure I understand the A -> B of your comment. Are you suggesting that they are readable currently, and may not be with .md files? Or that they are not and would need to be made so? OR something totally different?

(i should have quoted) it was in reply to: