Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update from rST to MyST and to common theme #187

Merged

Conversation

consideRatio
Copy link
Member

@consideRatio consideRatio commented Nov 3, 2021

.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

@lambdaTotoro
Copy link
Collaborator

Thank you for this work, it looks lovely! I'll merge it right away.

@lambdaTotoro lambdaTotoro merged commit 9d03a27 into jupyterhub:main Nov 4, 2021
@lambdaTotoro lambdaTotoro added this to the Version 1.1 milestone Nov 4, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Transition docs to use MyST?
2 participants