Documentation improvements

[laundmo]

The documentation for lona isn't very easy to read currently. There are a bunch of concepts that are only mentioned as a sidenote on some pages, and a mix of lona scripts and non-script apps is used.

Some tangible changes that would be nice to have:

• Split Widget docs from HTML
• Document different ways of accomplishing the same thing between scripts and non-script apps, especially in cookbooks
• Write some docs on the structure of lona, how things interact in general terms.

[fscherf]

@laundmo

I agree, but i have a few questions:

• Why do you want HTML and widgets be split? They are strongly related and work together.
• Where are the pitfalls for you when you try to apply a concept shown as script to a project and vice versa? What kind of information is missing here?

Documentation for the internal structure and protocol is truly missing and it's currently in the making

[laundmo]

Why do you want HTML and widgets be split? They are strongly related and work together.

the nodes generally map directly to to HTML tags and their functionality is quite limited. Widgets on the other hand can contain a lot of functionality, and are generally something i would consider very important to using lona. Currently, they have a short section at the bottom of the HTML page, which makes them easy to miss and seem like more of an afterthought than a big feature.

I would prefer them split off to make them easier to find in the documentation, easier to notice for first-time users and to allow for elaborating more on the features they offer than a short section at the end of another document.

Really, Widgets are just one example of odd grouping in the documentation: The same applies to Request and Response objects and to routing, which are currently on the Views document, which also makes them hard to find if you dont already know where to look.

The whole point is really to structure the docs in a way that makes the information easy to find. Maybe splitting the documents isnt really needed, but the sidebar should definitely allow for looking through it and seeing "Routing", "Widgets", "Request/Response objects" etc.

This also brings up another point: currently there is API reference and usage documentation mixed together. This makes it hard to find the documentation for arguments of a class/function since it's hard to find where that API reference is. One example being input event attributes: when writing a widget event handler, looking in the Views document for event attributes is not intuitive at all, after all im working on a widget and not a view.

Where are the pitfalls for you when you try to apply a concept shown as script to a project and vice versa? What kind of information is missing here?

one prime example is the auto-reconnect cookbook, it shows app.add_template, which obviously only exists in a script context since a non-script app doesn't have any app instance. Im still unable to figure out the equivalent of that method for non-script apps, since i haven't found documentation on adding templates to the main page anywhere, only overwriting the existing main template.

edit:

Here is an example structure i would propose, which is similar to that seen in many other projects:

End User Documentation
  - Views
      - explain what views are
      - some examples
      - advanced useage
      - link to Events
  - Widgets
      - explain what widgets are
      - some examples
      - advanced usage
      - link to Events
  - Events
      - mention that events are handled the same in a Widget or View (are they? seems like it to me.) 
      - bubbling
  - HTML Nodes
      - Usage
      - commonly needed attributes (link to reference for full list)
      - Styling
  - Templates/Frontends
      - ...
  - etc.
  
API Reference
  - lona
     - LonaApp
        - LonaApp.route
        - etc.
     - lona.html (list all nodes)
        - Node.hide
        - Node.class_list
        - etc.

Thats only a rough draft, the API reference can likely be auto-generated from docstrings with sphinx or a similar tool

[fscherf]

A settings variable? How would that look like?

[laundmo]

i mean, for adding templates in general a settings var isn't really viable. I was looking at it from the perspective of the auto-reconnect feature: thats something useful for development, so why should it take creating a folder, adding a file to it and then adding that folder to a different python file just to activate?

[fscherf]

The idea was that this example is completely self-contained. You can copy paste the code into one file and it works. When using a template as file, the user would have to setup a file structure in the right way to make this example work

[fscherf]

I like the proposed structure, but i would change up the order of pages to Views, HTML nodes, events and widgets last, so the topics start very basic and get more advanced towards the end.

[laundmo]

I like the proposed structure, but i would change up the order of pages to Views, HTML nodes, events and widgets last, so the topics start very basic and get more advanced towards the end.

ya, do your thing. its only a example.