search

TuringLang / docs

Documentation and tutorials for the Turing language
https://turinglang.org/docs/tutorials/docs-00-getting-started/
MIT License
225 stars 97 forks source link

Switch to Quarto #435

Closed devmotion closed 1 month ago

devmotion commented 4 months ago

I have made very good experiences with quarto, the multi-language successor of Rmarkdown: https://quarto.org

I think it could be useful and more future-proof to switch from Weave's jmd to Quarto's qmd format in the tutorials (possibly even larger parts of the website apart from docs could be generated with Quarto). The changes to the Markdown files should be fairly minimal, and with https://github.com/PumasAI/QuartoNotebookRunner.jl one can even avoid any Python dependency (the qmd files with Julia code blocks are converted to ipynb notebooks by QuartoNotebookRunner, and then quarto render can generate html output from them; only quarto itself (available as a jll IIRC) and QuartoNotebookRunner are needed, and the intention is to streamline this process further in the future and integrate QuartoNotebookRunner in quarto itself: https://github.com/quarto-dev/quarto-cli/pull/8645)

yebai commented 2 months ago

Seconded — Quarto is quite nice.

yebai commented 2 months ago

The stan team is planning to switch the entire Stan docs site to Quarto, see:

Let's share their website design...

shravanngoswamii commented 2 months ago

Switching to Quarto will make lots of things easier and better!! I suggest not only tutorials but Turing's website should also be switched to Quarto or maybe Franklin.jl (It's used in many websites including Julia and JuliaHub)

Why depend on Ruby and Jekyll when better alternatives exist?

These issues will be solved by switching without dealing with current complexities: #335 #270 Turing.jl#2154

JasonPekos commented 2 months ago

fwiw I wrote this pr and also the upcoming HMM marginalization tutorial (#330 ) in Quarto notebooks initially before changing some of the formatting to make them valid .jmd files.

This is just because the workflow is nicer, even ignoring deployment, and it takes <5mins a tutorial to swap them over.

If desired, I could add these into this repo in a currently unused /Quarto folder. Not sure what the details of a switch like this would look like.

yebai commented 2 months ago

Yes, we plan to switch to Quarto for docs website and tutorials.

shravanngoswamii commented 2 months ago

There are a lot of things I can see that need to be corrected:

  1. We need to work on proper redirection of links like turinglang.org/docs should redirect to current stable version of docs instead of 404ing and many more similar links...
  2. Turing Library API site's navbar does not have the option to go back to Main Turing's Website and It does not have the option to see Turing's doc
  3. Many links in the Tutorials Section are not working including Edit me, report issues and tweet this page, providing wrong link
  4. Link to style guide of How to Contribute page and Link to Invenia's style guide on style guide page are not accessible

And many more things...

These needs to be changed for temporary solution of TOC links: https://github.com/TuringLang/turinglang.github.io/blob/ae8c7176bd65c35fb9b5bb4381a9076a03554f82/_includes/sidebar.html#L123C1-L126C188

If desired, I could add these into this repo in a currently unused /Quarto folder. Not sure what the details of a switch like this would look like.

We can start this in a Quarto folder or maybe a new branch depends on the structure we will follow because in current structure Table of Content and Side Bar is being built manually, In Quarto it will generate by default (also Sitemap and other SEO things)

I think Turing site's search bar is not searching Docs and Tutorials, so that is also something that we need to consider...

yebai commented 1 month ago

This is now complete.