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

Migrate tutorial to use the quarto framework #63

Merged
merged 9 commits into from
Aug 22, 2023
Merged

Conversation

johnnv1
Copy link
Member

@johnnv1 johnnv1 commented Jul 29, 2023

This PR aims to move the kornia tutorials to use the quarto framework instead of sphinx to generate the tutorials webpage.

You can check out this change on the deployed version on my gh page: https://johnnv1.github.io/tutorials/

  • Main page
    page
  • Main dark
    page dark
  • tutorial page
    tutorial page
  • tutorial page code
    code part - light
  • tutorial page dark
    code part - dark

Improvements

  • The tutorials page will look like blog posts
    • With date, authors, thumbnails, etc
    • post
  • Tags system!!!
    • We can add categories into each tutorial, which allow the users to filter the tutorials
    • tags
  • better search engine
  • new UI
  • order by
    • orderby

What changed with this

  • readthedocs.org/ didn't support quarto so, we will need to move to use GitHub pages (TODO: need to configure the kornia/tutorials to publish the gh-pages from the branch gh-pages)
  • Instead of using the sphinx we need to setup the https://quarto.org/docs/get-started/
    • to mitigate the breaking changes, I added a make setup and make setup-quarto to help installing the dependencies
      • This command just works for linux -- the quarto is a binary and not a python package! To setup it up into another OS please check out the quarto documentation.
  • The UI/theme isn't the same from the main docs -- but we update it to look like it

What has been done

  • Minimal setup using Quarto
    • Delete sphinx and myst-st configs files
    • Initial configuration of Quarto (_quarto.yml)
    • Index page: A temporary page in a "blog posts listing" style before Refactor the main page #45 be done.
      • Should list our tutorials
        • Option for filtering, ordering and search
        • Tag!!! Be able to add categories "tags" into our tutorials, to be easy to navigate.
    • Update the Makefile
      • Update the generate command to convert inplace the notebooks: Just to check if they are a valid jupyter notebook.
      • Update the execute command to execute inplace the notebooks.
      • Update the setup command
        • Added a setup-quarto: Which will works just on linux machine. This command directly download the binary of quar»
        • Update the command to after pip install the dependencies execute setup-quarto
      • Added preview command to execute the quarto preview to test locally the webpages. Use this command to develop locally it's easily to debug with it!!
      • Added render command to build the webpages.
    • Added a CI to deploy the quarto build into GH pages!
  • Customize the theme to look like the main documentation (furo theme for sphinx)
  • Add a basic front matter into each tutorial! And update the "open in colab" badge to be a HTML tag instead of the markdow»
  • Add/generate a thumbnail and add it into the front matter for each tutorial!

@johnnv1 johnnv1 added the enhancement New feature or request label Jul 29, 2023
@review-notebook-app
Copy link

Check out this pull request on  ReviewNB

See visual diffs & provide feedback on Jupyter Notebooks.


Powered by ReviewNB

@shijianjian
Copy link
Member

LGTM. Is it possible to have sub-categories for a better organization of the right-side area?

@johnnv1 johnnv1 merged commit 4f5e239 into master Aug 22, 2023
3 checks passed
This was referenced Aug 22, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants