Add a docs/ site for Blink! #168
Conversation
Describes the basic usage for blink: opening a window, loading HTML/CSS/JS, and interacting with the window (`handle` and `@js`).
docs/src/index.md
Outdated
| Blink.jl provides a API for communicating with web pages from Julia. Pages may | ||
| be served over the internet and controlled from the browser, or served locally | ||
| via an [Electron](https://electronjs.org/) window. Blink can therefore be used | ||
| as a GUI toolkit – DevTools.jl for an example use. |
There was a problem hiding this comment.
I copied this from the README, but it seems a bit out of date. Does anyone use Blink as the backend of a web server anymore? this seems confusing to include in the main introduction to the package.
I would probably describe it instead as something like:
"Blink.jl is the Julia wrapper around Electron. It can serve HTML content in a local window, and allows for communication between Julia and the web page. In this way, therefore, Blink can be used
as a GUI toolkit for building HTML-based applications for the desktop."
What do you think?
docs/src/communication.md
Outdated
| ```@repl handler | ||
| @js w Blink.msg("press", [1,2,3]); | ||
| ``` | ||
| (TODO: is this on purpose? Can we fix this to allow variadic args?) |
There was a problem hiding this comment.
Is this on purpose? Maybe I should start a separate issue about it, but it seems weird that this is the API. Could the javascript function be changed to be variadic? (I actually don't know if you can do that in javascript..)
| w = Window(Dict(:show=>false), async=false) | ||
| ``` | ||
|
|
||
| This topic is covered in more detail in the [Communication](@ref) page. |
There was a problem hiding this comment.
I feel a bit weird about having repeated myself here, but i think it's good to have simple examples here and a full discussion of these complicated mechanisms there. What do you think?
|
Hey! :) I think it'd be nice to merge this in, even if not perfect, so that other people /might/ feel empowered to add to the docs. Could I set a deadline on this? Maybe i'll merge this in by this weekend or next monday or something if i don't hear from anyone? :) |
|
Yeah, feel free to merge this as soon as you're happy with it. This is great, thanks for the effort! :) |
|
Cool, I'll do it now! Thanks for the review @pfitzseb! :) |
|
Oh, maybe also add a docs badge to the readme. :) |
|
Ooh, yes, i meant to do that! Before i do that, i want to set up Travis to automatically rebuild the docs.
(I've renamed the account name it generated at the end, because it doesn't need to be from my laptop.. haha) julia> Travis.genkeys("Blink")
[ Info: add the public key below to https://github.com/JunoLab/Blink.jl/settings/keys with read/write access:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC71L/RxpPKYTEV9+D75Q6Kgum0pRVGkSTsNhTzb2VsKmJGL510OlyF+6YOvGQu43YBoeZblV9rIdkSoGfTu3U03BGgmsrgJrvrwHRs08SR2gSlbUJBQwi3krrT1pwqc3CS5OwaQeCtl/vtQLfFDfnfkh1xlVwymvJzaxl+fmf+u0GSp1ykpi3l2aaHURffyZ0/XkFNei6UKlf3xx4HV7pkk8MNrclQq1XUHW70ucF9IYGsBYPUiaKZxnrC5iwj0zmEW6VosHRLvqZFbHw3+iPWYfs8ggoxe2ceIzGzNyQoMvz9TWDcOLhw7RayQ51qHH+8Z34AIYTQ7XnOcIuUwahx daly@nathans2016mbp.lan
[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.org/JunoLab/Blink.jl/settings with value:
<REDACTED :P> |
|
Ah, actually, I think there is no docs site yet until we do this actually? Cause then we need to run the |
Updating the intro paragraph per the discussion we had in #168
Step 3 of #160: Create a documentation site using Documenter.jl
Here is a preview (I think) of what it would look like when we A) merge this in, and B) turn on automatic docs building and deploying through Travis:
https://nhdaly.github.io/Blink.jl/stable/
I'd love to talk through this a bit before merging it! :)
Any high-level thoughts about the structure of it, or nit-picky thoughts as well. It's certainly not finished, but I think it's in a good enough state that it's worth putting out there now!
Obviously we haven't finished adding docstrings to all the names in the package, but we can just also add them to the generated
docs/as we add them! :)Let me know what you think!
Thanks!