Codecov Report

Merging #1526 (3118a14) into master (77e7ef6) will increase coverage by 0.00%.
The diff coverage is n/a.

❗ Current head 3118a14 differs from pull request most recent head 382f8c6. Consider uploading reports for the commit 382f8c6 to get more accurate results

@@           Coverage Diff           @@
##           master    #1526   +/-   ##
=======================================
  Coverage   95.21%   95.22%           
=======================================
  Files          46       46           
  Lines        6483     6494   +11     
=======================================
+ Hits         6173     6184   +11     
  Misses        310      310           

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 77e7ef6...382f8c6. Read the comment docs.

Hey, so the issue you're referring too is super old. Back then, the docs was still hosted on gh-pages branch but I eventually merged it into the master branch.

I much prefer markdown than RST and I don't have any complaints about the docs site being built in Jekyll.

The biggest thing why I made this PR was because readthedocs has version control and so we wouldn't always have to add New in version 1.9.0. like here.

You also don't have to use the browser but you can generate pdf, epub or man pages as well.

Also look at the API Reference. This is also impossible for Jekyll.

If you prefer md I can port the content pages back to md but I wouldn't port files like docs/index.rst or api.rst, because they only contain sphinx contents like toctree or autoclass. I don't think that will be a problem because you can use markdown and restructuredtext at the same documentation.

Edit: I ported every restructuredtext file to MyST (Markedly Structured Text, Markdown but with sphinx options).
Edit2: Apart from api.rst

@selwin If you want to look at this documentation, I created a temporary readthedocs link here.

Also look at the API Reference. This is also impossible for Jekyll.

I think this is the only real win for me.

I ported every restructuredtext file to MyST (Markedly Structured Text, Markdown but with sphinx options).

I think I still prefer using .md or some of the more well supported markdown flavors for portability purposes (maybe CommonMark or Github Flavored Markdown?). This will make it easier in case that we need to switch to a different docs infrastructure.

I looked at the test site you made; some of the styling is a bit messy so I suppose if we end up switching to Sphinx, we should use one of their more established themes.

My worry with this accepting a pull PR like this is that I don't fully understand Sphinx and the build process so it may be a bit troublesome to maintain in the long run.

Let me think about this a bit more. I will get around to reviewing your CLI PR sometime this weekend, I promise.

Thanks for all your efforts, tackling big issues like this. It's much appreciated.

@selwin

I think I still prefer using .md or some of the more well supported markdown flavors for portability purposes (maybe CommonMark or Github Flavored Markdown?). This will make it easier in case that we need to switch to a different docs infrastructure.

If you look at 0d3f7d8, you see that I switched to MyST. This is a Markdown flavor which supports rst features:

I looked at the test site you made; some of the styling is a bit messy so I suppose if we end up switching to Sphinx, we should use one of their more established themes.

Ok, which themes do you prefer.

If you look at 0d3f7d8, you see that I switched to MyST. This is a Markdown flavor which supports rst features:

I'm aware, but what I'm saying is I'd rather switch to common mark or Github flavored one for portability purposes (easier to move to a different docs infrastructure :).

Ok, which themes do you prefer.

I think Furo: https://sphinx-themes.org/sample-sites/furo/