Changed Docs to Markdown Format from reStructuredText Format

[DhruvSondhi]

Hello,
This PR aims to propose the idea of migration of the documentation from .rst format to .md format for easier editing & maintenance 😄
Implements #977

[DhruvSondhi]

Hello,
We have completed about 85-90% of the migration to markdown format for Read The Docs. But the following problems are arising, due to non-native support for .md file format in Sphinx Documentation Generator :

• Upon the conversion of all the files from .rst to .md, the following files were most affected:
  1. Index.md
  2. use_guide.md
  3. search.md
• Main Problems :
  1. index.md doesn't have the working toctree as the .rst counterpart had.
  2. index.md is also not being rendered in HTML format even though, it is being rendered in normal markdown format.
  3. If we include any reStructured Text syntax then the document doesn't render markdown syntax 😞
  4. All Hoverxrefextension's commands & annotations were removed by me as it doesn't render correctly { Markdown doesn't support hoverxref extenstion}
  5. user_guide.md doesn't render as the HTML page & does raise some trivial warnings :(
  6. inline syntax, from Myst & rst, raises an error which is evident in both files
  7. Again, toctree is not working & hence the referencing of the page is not possible & Index for referencing on the page remains empty
  8. nbSphinxGallery doesn't show the gallery & the thumbnails for all the examples notebooks ... Update extension nbSphinxGallery is not supported 😞
• removing Directive syntax from any of the markdown generated pages, allows the page to be rendered prefectly ... Issue is with the Directive syntax parsing in Myst 😞
• Will add more issues as and when I encounter them or will try to fix multiple 😄

UPDATE: Fixed most of the errors.
NEW PROBLEM: nbSphinxGallery

UPDATE 2: Fixed everything ... Ready to go 😄

[codecov]

Codecov Report

Merging #1073 (20918c2) into master (9b94129) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1073   +/-   ##
=======================================
  Coverage   89.52%   89.52%           
=======================================
  Files          75       75           
  Lines        3991     3991           
  Branches      343      343           
=======================================
  Hits         3573     3573           
  Misses        326      326           
  Partials       92       92           

---

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 9b94129...20918c2. Read the comment docs.

[astrojuanlu]

The builds are failing:

ModuleNotFoundError: No module named 'myst_parser'

@DhruvSondhi could you please add the necessary modules to the dev requirements in pyproject.toml so they get picked up by https://github.com/poliastro/poliastro/blob/master/.readthedocs.yml ?

Then mark this pull request as ready for review so we can have a closer look :)

Great job fixing the remaining issues!

[astrojuanlu]

This is awesome work, thanks a lot @DhruvSondhi! 👏🏽 There were a lot of challenges along the way, but you almost got it working. Even the autoapi and hoverxref extensions.

However, the notebook gallery lost several thumbnails and, most importantly, cell outputs. I think we should figure this out before merging this PR.

One obstacle might be that one can't register two processors for the same extension:

Extension error:
source_suffix '.md' is already registered
make: *** [Makefile:61: html] Error 2

One silly idea that I had was to use a different extension, like .nmd, for notebooks. But I don't know if this breaks other stuff.

When we are out of silly ideas, I think we should get in touch with nbsphinx and executablebooks authors, with a Short, Self-Contained, Correct Example to reproduce the problem, and inquire about a way forward.

If combining these two systems is impossible, we should reach out to MyST-NB authors to ask whether a "gallery-like" feature is in scope.

And finally, if this is truly impossible, we could consider alternatives for the notebooks, like having only links to Binder. This has obviously pros and cons.

[DhruvSondhi]

After checking through all the documentation thus generated after the migration to Markdown, the following issues are found :

• The nbSphinx gallery doesn't work (as stated above already by astrojuanlu) [Fixed]
• The nbSphinx extension also had the functionality of executing & displaying all the outputs thus generated, but now doesn't work 😞 [Fixed]
• Issue Investigate sphinx-autoapi warning #1077 states problems with warning related to the Autoapi extension & is linked with the Search functionality of the document being redundant as of current status 😞 [Not In Scope Of This PR 😉 ]

[astrojuanlu]

Closing and reopening to try to trigger pipelines.

[astrojuanlu]

@DhruvSondhi, #1077 is not linked to Search. see #1079

[astrojuanlu]

Awesome work! Did a first superficial review and left some comments.

To clarify: the output looks great and I'm looking forward to merging this!

[astrojuanlu]

This is huge and I did not review everything in depth, but after a quick look on the output, I think this is ready to be merged! If we find small formatting issues, they can be fixed afterwards.

[astrojuanlu]

Congratulations @DhruvSondhi for this pull request! It was not an easy task and the final results are awesome 🚀