docs: update from rST to MyST and to common theme #187
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
.rST to MyST .md files
This PR transforms .rST documents into .md documents with MyST syntax that complements the markdown syntax to be able to link to other pages and such, and use the Sphinx common roles and directives.
For more details about MyST, see https://myst-parser.readthedocs.io/en/latest/
New documentation style theme
We have been using the sphinx theme called pandas-data-theme. I would say it doesn't look great yet because we have our docs in ~3 pages, so it's a bit too much to have left/top/right sidebars to navigate that. But, if we structure the documentation a bit to be in smaller parts, it would look fine, and we could also remove a sidebar otherwise.
I figured such refactoring would be sensible to do in a separate PR. We can retain use of the old alabaster theme as well, but I figured I go for the new theme right away and didn't test retaining the old
alabaster
theme.Dedicate source folder
This PR also makes the documentation have a dedicated source folder so it's easier to overview the actual source content from misc files and folders like make.bat/Makefile/requirements/_build that aren't relevant in the same way.
Accept long line lengths
Some comments with a long URL caused flake8 to react, I felt it was a pointless thing to enforce strictly when we now have black that will make code go to a certain max length, but not comments.
Closes #176