Docs, rst vs md

[Lagicrus]

Why does some of the documentation for Sanic use .md and some use .rst? Would it not make more sense to have it all under one file extension?

[harshanarayana]

@Lagicrus Last time I updated the documentation section, I did a bunch of changes and moved quite a few files to rst. Migrating md to rst is pretty straightforward with a simple script or a 3rd party utility that is available. Let me know if you want to take up migrating them to a common format.

I am personally in favor of rst but md is equally good.

[Lagicrus]

I am tempted to do a PR to move from one to the other, it was just mainly a question as to why we were using both in the first place.
I am more in favour of md as I personally find it easier to write up & my IDE seems to hate rst at the moment so thats fun. Out of interest why do you prefer rst?

[harshanarayana]

@Lagicrus I have been using rst for a long time. Coming from a LaTeX world, the suffering that came with rst was nothing. 🤣

Please feel free to open a PR to migrate the documents to a common format across the board. I will be more than happy to help you in anyway required.

[Tronic]

The heading format of rst (ASCII underlining) is retarded, but other than that the syntax seems quite usable (and in a few ways better than Markdown, I suppose). The problem is that there are a lot of subheadings in documents, and ## Subheading is so much easier to use + clear about the nesting level.

[harshanarayana]

\documentclass{readme}

\newcommand{\stupidsubhead}[1]{{\Large #1 \vspace{2ex}}}
\begin{document}

\section*{This is what pain looks like}
\stupidsubhead{If only I knew better}

\end{document}

I am okay with md being the default mode for documenting. However, sphinx's default suggested format is rst if I remember correctly. @huge-success/sanic-core-devs What do you guys think?

[Tronic]

Argh. And the worst part it that LaTeX just won't die. Who designs a language where using _
in a code block just blows up the entire system with an uncipherable wall of text as error message, unless you remember to include the underscore package in your header. Some idiots even ported LaTeX to Javascript as MathJax (which works slightly differently so that the hacks you learnt to use in LaTeX to get things done don't work the same way anymore).

[Lagicrus]

\documentclass{readme}

\newcommand{\stupidsubhead}[1]{{\Large #1 \vspace{2ex}}}
\begin{document}

\section*{This is what pain looks like}
\stupidsubhead{If only I knew better}

\end{document}

I am okay with md being the default mode for documenting. However, sphinx's default suggested format is rst if I remember correctly. @huge-success/sanic-core-devs What do you guys think?

That's interesting regarding sphinx's default, didn't realise you could mention teams (which 404'd amusingly) so thats cool, but then again sphinx doesn't seem to break just yet with md so woop, and in my opinion doing it in .md makes it more open and easier to contributors to help out compared to what I believe is the more rst?

[harshanarayana]

@Lagicrus Absolutely. For someone starting on open-source contribution journey, md files are much easier and like you mentioned, it is lot more IDE friendly. I am perfectly okay to move all the documentation files to md so long as we can retain most of the structure around it.

We also have some inline code documentation where some of them are in rst while others are in md. Maybe we can take up that as a different work item?

[Lagicrus]

I am fine with working on a PR to move the majority, if not all docs (docs/sanic) to MD.
In theory, correct me if I am wrong, but the structure shouldn't need to change right? In theory isnt it just swapping out one file for the next?

We also have some inline code documentation where some of them are in rst while others are in md. Maybe we can take up that as a different work item?

You have me at a loss with that one

[harshanarayana]

@Lagicrus

In theory, correct me if I am wrong, but the structure shouldn't need to change right? In theory isn't it just swapping out one file for the next?

Yes, that is correct. Rename the files and fix the syntax to make it md friendly.

[Lagicrus]

Interesting roadblock, so far some files can easily be converted like the asyncio_python37 file or the cookies file. Just regular, "put text in here and solved".
But there is an issue with other files such as the api_reference, changelog, contributing and index as they are based around importing other files into it
Which leads me to ask, do we now convert all we can over to MD besides the files who have ingrained rst features OR do we move over to full rst instead so we keep those features and don't use two setups at once?

If I have missed a markdown equivalent of

.. include:: ../docs.rst

tell me but I am so far doubting it

[Tronic]

One can add symlinks to git, right?

[Lagicrus]

Unsure, to my understanding the include stuff within rst is so you can include actual files within other files if that makes sense. Examples.rst is a great example of that, or the changelog.rst.

Currently, I am moving them all over to rst as it seems to be the solution, should be done by the end of the day.

Question, do I put into the contributing.rst file, under the documentation header, the format I used for header layouts to keep the same format across all files? As with rst you need to use different symbols to show that it is another tier of header compared to md's the more #'s the smaller

[harshanarayana]

@Lagicrus I moved the changelog file that was initially in markdown format to rstfor this very reason that I can cross reference and keep only one file as source of truth.

I think for the time, we can move all the standalone rst into md and then find a way to easily manage the files that either reference or import other files.

The examples section of the document is another major one where everything in cross imported.

@Tronic I tried symlink of the md files. But the sphinx tooling doesn't seem to like it.

There are options such as pandoc that we can leverage. But that just makes everything a lot more urgh!!

Currently, I am moving them all over to rst as it seems to be the solution, should be done by the end of the day.

If you have already started doing this, then let's stick to moving all of them over to rst then. Hit me up if you need any help.

[harshanarayana]

@Lagicrus So long as the documentation page doesn't drastically change between the releases causing confusion, please feel free to change/restructure things.

[Lagicrus]

@Lagicrus I moved the changelog file that was initially in markdown format to rstfor this very reason that I can cross reference and keep only one file as source of truth.

Yeh that makes perfect sense, I can definitely see the advantage of that

If you have already started doing this, then let's stick to moving all of them over to rst then. Hit me up if you need any help.

Yeh I will don't worry, thanks for the offer :)

I got bored at night so I started working on this and I quickly just started working through it lol

Had a weird bug with the table which I will either link later when I am back at my machine or when I do the PR to fix it

[Lagicrus]

Added a Draft PR #1698 regarding this @harshanarayana @Tronic :)