Discussion regarding the editing of the Yao website

[VarLad]

@Roger-luo
Lets discuss a few ideas we can use to better edit the Yao website (the tutorials part)

[VarLad]

The simplest way I could think of, was to have a separate repo for tutorials (we can just use https://github.com/QuantumBFS/tutorials)

There we can just fork and edit the MITs191 github repo and deploy it to quantumbfs.github.io/tutorials

In the header of yaoquantum.org, we can redirect the tutorials to our above created page

[VarLad]

@Roger-luo One solution I can think of, is to keep header persistent throughout the tutorials

As in, it won't disappear as you keep scrolling down, in tutorials
Another thing, I'd like to do, is to cut out out a bit of the footer for the tutorial page, as if I make that persistent, it'd take up quite a bit of space
We can just include the the slack link and the issues link in the header
All of this, specifically for the tutorials page. No change to the remainder of the site whatsoever

We can keep the below information either in the welcome page, or somewhere in the side bar

The Yao Framework

Extensible Efficient Quantum Algorithm Design For Humans.
© QuantumBFS. Website built with Franklin.jl and the Julia programming language.

[Roger-luo]

I think a good reference is pennylane's website: https://pennylane.readthedocs.io/en/stable/

It's written by professional frontend developers, so we could use this as a reference.

[VarLad]

How about https://qiskit.org/textbook/ch-states/case-for-quantum.html
？

[Roger-luo]

Yeah this one looks great too, I guess the problem is our banner has a very inconsistent style with the sidebar... and we don't have a good UI on the banner to guide people to other places comparing to this IBM page.

[Roger-luo]

would be nice if you could implement a small demo page @VarLad I think you could post the link of the demo page here.

One solution I can think of, is to keep header persistent throughout the tutorials

Yeah, I agree, this would help people go to other pages.

We can keep the below information either in the welcome page, or somewhere in the side bar

True. I think we can have a smaller footer for the tutorial page and other content dense page.

[VarLad]

@Roger-luo Take a look at this sample https://varlad.github.io/Spring21/x/
The repo is https://github.com/VarLad/varlad.github.io

This implementation is stable, with the banner and everything. I don't think we need the footer（We can easily include that information in the sidebar and that saves space）

The only problem I'm facing is padding (a part of sidebar and notebook get covered by the header)

Since we're using custom css and a different template here, I think it'd be easier to deploy the tutorials on a different repo. That way, anyone can customize it without caring about how it affects the site

Any ideas regarding the two problems are welcome

[VarLad]

Please confirm if you agree with this approach
If you agree, all thats left is to tweak the padding and to fill out the incomplete contents

[VarLad]

Unitary Hack will be over soon. I hope I can complete this in 24 hours

[Roger-luo]

I think the current tutorial page looks good in general, but need to make the sidebar style consistent with banner (not use the MIT course CSS)

Since we're using custom css and a different template here, I think it'd be easier to deploy the tutorials on a different repo. That way, anyone can customize it without caring about how it affects the site

the other problem is we need to setup the pipeline for the tutorial where we:

1. build the tutorial page along with homepage in one repo
2. host the tutorial pluto script files in the tutorial repo so that one can easily download and run locally

Unitary Hack will be over soon. I hope I can complete this in 24 hours

I don't think we can finish this in 24hrs, but if you have time in the summer, maybe consider apply our summer of code (but it will require you put more time into this tho)

[VarLad]

the other problem is we need to setup the pipeline for the tutorial

@Roger-luo Take a look here
https://github.com/VarLad/tutorials
If you push on my tutorials fork, that automatically pushes here: https://github.com/varlad/varlad.github.io
The contents of the notebooks folder of tutorials gets copied into the notebooks folder of the site

I consider that one complete. Is it okay if I make a PR to the tutorials repo?

[Roger-luo]

That would remove the navbar I guess. You don't need the navbar then, in the docs?

no, as I mentioned in the issue, you will need to implement JuliaDocs/Documenter.jl#1132

the current implementation is only a workaround, that's why the code is copy pasted, instead of replacing the Documenter functions by writing monkey patch, we should do it by actually implementing it.

[VarLad]

The docs folder (https://github.com/QuantumBFS/Yao.jl/tree/master/docs), do you need a pipeline from it to QuantumBFS/Quantumbfs.github.io/docs folder or something, and then run make.jl from quantumbfs.github.io?

Or do you want to run the make.jl in Yao.jl, and deploy it to quantumbfs.github.io repo?

[VarLad]

@Roger-luo I believe we can achieve the header with Franklin, without having to implement it in Documenter

[Roger-luo]

Are you doing it via iframe? If so, I don't think it's a good idea using iframe since it can easily break the style.

[VarLad]

I'm aware of that
But using with iframe-resizer, I've been able to get a somewhat consistent solution.

I've figured out how to build the docs from the site and deploy them with the site but the solution would take some time to implement. I'll put the demo here when its done.

[VarLad]

Making a to-do list here

• Making the tutorials render properly on a smartphone/smaller screen. MIT site does it by making the sidebar go on top. An alternative could be to build a toggler to hide it.
• Using the PlutoSliderServer to create the htmls instead of the current PlutoBinder setup.
• Update everything to the latest. Latest version of Pluto provides the "Edit or run on binder" by default on the top
• Fix some notebooks. Use the PackageSpec from Pkg
• Make the docs more compatible with the Yao site and banner.

[VarLad]

Hmmmm.... I see. Regarding security issues, Mozilla pushed forward a solution to isolate them.

Also, my point being, my iframe setup is too simple to cause problems (for the Documenter part). As for the tutorials part, iframes is kinda broken there. We need a better iframes solution there or if possible, an iframes free solution (which I think is possible, but would require a lot more experimentation)

[VarLad]

just add a more detailed table of content on the right hand side (which is entirely blank) and make the entire doc page centralized

Okay, so display a list of all the methods in the page in the right side?

[Roger-luo]

I think to have an iframe free solution, we just need to revise Pluto export function to generate the head and div seperately, but I'm not sure how.

For documenter I think asking Documenter to export markdown and let franklin render it would also be a solution.

[Roger-luo]

by table of content I mean the markdown table of content, documenter only display upto 2-level headers, and by more detailed TOC means to display 3-level headers or 4-level headers, since the doc page may not contain a reference table, I think this design is quite common in markdown static websites, you can also check some jekyll themes as a reference.

[VarLad]

@Roger-luo Pluto generates a bunch of pluto-cells I think

Ever tried copying pasting the pluto cells from inside the container to the side...?
For this, someone needs to be more intimate with both Pluto and Franklin... Also, there's the problem of colliding headers (the styles techically). I don't think normally one would occur though.
What I do know from this is, if we do implement a solution like that, the users themselves have to be intimate enough with HTML to solve any issues and the implementation won't be very general.

Solutions involving iframes basically display a complete site within a site. Displaying two different web pages in one. Thats why there's problems with its implementations I guess.
But I think iframes solution would be much easier to use if the users get problems (because then they only have to worry about how to fix the iframe as one entity)

[VarLad]

@Roger-luo I ran into some problems with my iframes implementation today (with the docs integration)

I can fix that today, but I guess we'll get more issues like this in the future.
We need a solution using divs
For now I can try writing a CI which somehow weaves the header and the docs (based on your patch)
As for your idea of allowing more general HTML manipulation in Documenter, I think I'd need better instructions on what to make.
As for the 2nd Documenter issue, I can make a function to parse the md files and make a div of ToC out of them. Its easy enough for the maintainer to apply that function in Documenter, so if he ever wants this feature, it'll take him 5-10 mins to integrate it into Documenter
Edit: Instructions just came from the maintainer. On it!

[VarLad]

Huhhh... any ideas where to go with the header/navbar-in-docs?

[VarLad]

@Roger-luo For the final problem: tlienart/Franklin.jl#474 (comment) :)

This sounds interesting (although time taking). Basically a package with a lot of hfuns users can import!

[Roger-luo]

I see, that means some sort of plugin system needs to be built for Franklin then

[VarLad]

Yep! A package which has some custom hfuns which others can import!
This needs a better look into how Documenter works (specifically the fucntions that generate the HTML)!

[VarLad]

@Roger-luo Regarding JuliaDocs/Documenter.jl#1563

Just FYI, I can inject this modification into the generated docs using a CI, without adding it as a feature to Documenter.jl. Seems easy enough.

[Roger-luo]

it seems Documenter people prefer us experimenting this outside the package first, so yeah let's do the evil thing to change the modification first. I assume mostly this only requires a CSS change and an extra TOC generation. The TOC can be generated from the Markdown AST directly without implementing your own parser.

[VarLad]

I just used https://tscanlin.github.io/tocbot/

[Roger-luo]

this looks good to me in general, can we open a PR for this first?

[VarLad]

@Roger-luo #284

Demo: https://varlad.github.io/Yao.jl/dev/man/registers.html

[VarLad]

The code is outright demonic but kinda works! :)