Redesign the site using jupyterebook

seismo-learn / seismology101

Tutorials for absolute beginners in Seismology

https://seismo-learn.org/seismology101/

66 stars 18 forks source link

Redesign the site using jupyterebook #507

Closed seisman closed 2 years ago

seisman commented 2 years ago

PREVIEW: https://seismo-learn.org/sitepreview/seismo-learn/seismology101/jupyterbook/

In this PR, I try to migrate the who documentation from Sphinx to JupyterBook.

JupyterBook is built on top of Sphinx, so you can think that it's a wrapper of Sphinx.

Advantages of JupyterBook:

The default theme is the sphinx-book-theme, which looks pretty good
It supports writing documentation in Markdown, which syntax is easier than ReST.
It has built-in support for copy-button, panels, and dropdowns. In Sphinx, we have to use many extensions to have these features.
It also has more feature like "side notes", which is better than dropdowns in some cases.

Disadvantages of JupyterBook:

Some texts like "Previous" and "Next" are still English-only.

github-actions[bot] commented 2 years ago

This comment was written by the Continuous Documentation bot!

Preview: https://seismo-learn.org/sitepreview/seismo-learn/seismology101/jupyterbook/index.html
Commit hash: c3c7f9946b590fa8b4963ae76f587fdbe9079b1b

github-actions[bot] commented 2 years ago

Images automagically compressed by Calibre's image-actions ✨

Compression reduced images by 7.1%, saving 695 bytes.

Filename	Before	After	Improvement	Visual comparison
`source-book/logo.png`	9.62 KB	8.94 KB	-7.1%	View diff

19 images did not require optimisation.

Update required: Update image-actions configuration to the latest version before 1/1/21. See README for instructions.

seisman commented 2 years ago

I've migrated the first two parts from Sphinx (ReST) to JupyterBook (Markdown). I think the migration is pretty smooth, and expect to finish the remaining chapters in less than one hour.

@core-man Please see if you agree we should migrate to JupyterBook.

github-actions[bot] commented 2 years ago

Images automagically compressed by Calibre's image-actions ✨

Compression reduced images by 33%, saving 28.38 KB.

Filename	Before	After	Improvement	Visual comparison
`source/logo.png`	86.00 KB	57.62 KB	-33.0%	View diff

19 images did not require optimisation.

seisman commented 2 years ago

Ping @core-man for review.

core-man commented 2 years ago

Ping @core-man for review.

I've finished reviewing the new structure, and am reviewing the content now. I will finish it tomorrow.

seisman commented 2 years ago

Ping @core-man for review.

I've finished reviewing the new structure, and am reviewing the content now. I will finish it tomorrow.

I don't think you need to review the content, because the conversions from ReST to Markdown are done automatically. If we decide to use jupyterbook, we can merge this PR and then fix any issues later.

core-man commented 2 years ago

Ping @core-man for review.

I've finished reviewing the new structure, and am reviewing the content now. I will finish it tomorrow.

I don't think you need to review the content, because the conversions from ReST to Markdown are done automatically. If we decide to use jupyterbook, we can merge this PR and then fix any issues later.

Sounds good~