genieframework / genieframeworkdocs Goto Github PK

Add the complete API docs from genieframework.com/docs
This entails

• Deciding where to put the API docs. Probably in a new subsection /reference/API
• Listing the packages to include. Genie, Stipple. SearchLight, StippleUI...
• Fixing the API docs builder if it doesn't work

Eventually, the API docs could be grouped by feature (server, database) instead of package name. But that's for another time.

https://genieframework.com/docs/genie/v5.11/tutorials/Initializers.html

https://github.com/GenieFramework/Genie.jl/blob/master/docs/src/tutorials/17--Working_with_Web_Sockets.md

I ran a broken link checker and find out we've got 27 broken links. We'll work on fixing them.

Give an overview of the framework and direct users to the appropriate guides for the app they want to build: dashboard, multipage, API

Reference: https://genieframework.com/docs/genie/v5.11/tutorials/Overview.html

@vrkansagara mentioned having issues getting the VM sizing right when deploying a Genie app. In the workshop, we recommended 2GB RAM for deploying on fly.io. We need to do better estimates and add them to the workflows section in the reference

The server link in /docs/reference/overview does not work, 404

What they are
How to define (@app, @handlers)
How they work
Under the hood: Observables.jl, macro expansion, handler storage

JuMP docs has a tutorial on sering a model via an API using HTTP.jl. We could do one with Genie like what we did in the workshop with the neural network.

https://jump.dev/JuMP.jl/stable/tutorials/applications/web_app/

Need to go through the guides and determine:

• If they are up to date
• If their content belongs to the reference docs or tutorials sections

Other tasks:

• Change headings to enable TOC display
• Check for broken links or images

The readme lists different ways of writing Stipple apps that use @vars, @handlersand @app, among other features. This should be simplified to the template we're currently recommending, like the one in the your first dashboardguide.

https://github.com/GenieFramework/Stipple.jl

Should extend docs on the various plugins, and add the plugin development guide from https://genieframework.com/docs/genie/v5.11/guides/Genie-Plugins.html

Add the MVC guide as a tutorial

API & Components buttons are focused and not clickable

There's a link in the readme to APIDocs repository. But it looks like it's not public right now.

Right now the for loop example (used for multiple toggles) is only implemented in HTML. Need to do it in Julia as well
http://localhost:3000/examples/reactive-ui/multiple-toggles

The examples repo is here: https://github.com/BuiltWithGenie/CodeExamples

This guide has a lot of info covering views, databases and controllers. Each part should go into the corresponding section in the references

https://github.com/GenieFramework/Genie.jl/blob/master/docs/src/guides/Working_With_Genie_Apps.md

Explain how to iterate to generate multiple elements in a loop. MWE:

  module App
  using GenieFramework
  @genietools

  @app begin
    @out data = [
      ("msg1", "https://www.kasandbox.org/programming-images/avatars/spunky-sam.png"), 
      ("msg2", "https://www.kasandbox.org/programming-images/avatars/spunky-sam-green.png"), 
      ("msg3", "https://www.kasandbox.org/programming-images/avatars/purple-pi.png"),
    ]
  end
  
  function ui()
    row([card(style="margin: 10px;", @recur("item in data"), [
        p("{{ item[0] }}"),
        p("{{ item[1] }}"),
        imageview(src="{{item[1]}}")
    ]),])
    row([card(style="margin: 10px;", @recur("[msg, url] of data"), [
        p("{{ msg }}"),
        p("{{ url }}"),
        imageview(src=:url)
    ]),])
  end
  
  @page("/test", ui)
  end

As of now there's several ways to run an app, depending on which generator was used to create it. Either Genie.loadapp or including app.jl, server.jl, bootstrap.jl. We should try to have a unique way across all types of apps, probably Genie.loadapp()

Like the section in the guides landing, but with some links to the packages

Apparently Documenter.jl adds a link whenever a type appears, like Integer. We have to remove these links or fix them.

As of now, we have two doc sources: genieframework.com and learn.geniecloud.io

The ones on geniecloud are the newest, and their content includes:

• Task-oriented user guides
• Concept-oriented reference documentation. Includes API documentation.
• Tutorials for building entire apps or learning about specific features

The reference docs are organized by logical component and features. At the top level we have Server, Reactive UI and Database. Then come the features of each, such as routing, views.

The genieframework.com docs page is a mix of guides and API docs, and it is organized by package (Stipple, Genie, SearchLight).

The idea is to adapt the content in genieframework.com to the learn.geniecloud structure.

Starting with the first Genie app example, explain how to add a data model and work with it in a database. The guide should include:

• DB creation
• Automatic migration (New Searchlight feature?)
• Persisting, loading and searching for objects

DB section in MVC guide for reference.

A site with all the in-development content merged into it so that it can be easily browsed. It should merge every commit from branches with a PR open. Ideally a PR should be labelled as "auto merge" before being included in the workflow

After the move to a subdomain, some links are broken like

• In reference/overview the server link directs to docs/server/api/server, and the App Gallery link links to localhost

• The links to server, reactive UI, database. These are implemented with a redirect in their 0.index.md file, which needs to be updated

Explain how code reloading works by default, and how to set it up to watch for changes in the code. This should go into the Reference/workflows section

https://github.com/GenieFramework/StippleUI.jl

  module App
  using GenieFramework
  @genietools

  @app begin
    @out data = [
      ("msg1", "https://www.kasandbox.org/programming-images/avatars/spunky-sam.png"), 
      ("msg2", "https://www.kasandbox.org/programming-images/avatars/spunky-sam-green.png"), 
      ("msg3", "https://www.kasandbox.org/programming-images/avatars/purple-pi.png"),
    ]
  end
  
  function ui()
    row([card(style="margin: 10px;", @recur("item in data"), [
        p("{{ item[0] }}"),
        p("{{ item[1] }}"),
        imageview(src="{{item[1]}}")
    ]),])
  end
  
  @page("/test", ui)
  end

only with src=:symbolit works. Must explain this

Just a quick guide showing the steps to build an app with GB. Like the quickstart guide we had in Genie Cloud

Detail how to add reactive pages to an app

The "your first app" guide presents the standard webservice structure with pages containing standard (non-Vue) components. If the user wants then to add reactive pages, they can follow the guide on "Adding reactive pages"

However, it could be good to have another end-to-end quick guide on building reactive dashboards, as this is a very common use case. If they then want to evolve the app to something more complicated (multiple pages, databases), they can head to the "Organizing your code" guide and follow from there.

Explain how to use it, the type of components it generates (Quasar), and provide a list of most common calls.

Reference: https://learn.genieframework.com/guides/no-code-ui-editor/designing-the-ui-lowcode

there should be less clicks between genieframework.com and the documentation

Explain how a reactive page is created and sent to the browser

• Route
• Reactive model creation
  • Observables
• Vuejs SPA
• Browser rendering
• Websocket communication

Reference: https://genieframework.com/docs/stipple/v0.25/guides/Stipple-LifeCycle.html

https://github.com/BuiltWithGenie/NNtraining

These past few months we've focused on Reactive apps, which follow the app.jl+app.jl.html structure. However, there's also the webservices and MVC structures. They're fairly different since reactive apps are based around the @app block, and the others rely on a main routes.jl, controllers, views, and models.

What should we introduce users to first? This would depend on what they're trying to do:

• A dashbod --> reactive app
• An API --> webservice
• A simple static site --> webservice
• Anything with models and databases --> MVC, perhaps MVC+reactive

We need to be careful in the introduction so that users realise that there's more beyond Reactive apps but without introducing too much complexity.

As of now, the docs use the Genie.Generators to create webservices/MVC architectures. These are a little hard to grasp: there's many autogenerated files, and names like "MVC" may not mean much to the user.

I'm thinking that we could develop some simple default templates for the various cases, and eventually build generators for them. Moreover, I'd like to hide away all the bootstrap and config files that come with the generators. I've made an initial attempt at a template for a web service here:

https://github.com/BuiltWithGenie/WebServiceTemplate

something like "this guide comes from the old Genie.jl docs (link) but it can be followed normally".

How to deploy an app to a server without using containers.

1. Download and instantiate Genie app
2. Configure as a service with systemctl or with @vrkansagara's guide
3. Reverse proxy with NGINX

Template: https://genieframework.com/docs/genie/v5.11/tutorials/Deploying-Genie-Server-Apps-with-Nginx.html

Adapt content from existing gf.com guide

Like in the workshop. How to create an API and document endpoints with swagger

We have a lot of questions in the Discord server that are not reachable via search engines. We should export the forum threads and add them to a page in the docs so that people can at least read them. If they want to participate, then a link should direct them to the thread.

We could use this to export the forum https://github.com/Tyrrrz/DiscordChatExporter