Ligare documentation

[aholmes]

Suggestions, comments, errata for Ligare documentation at https://uclahs-cds.github.io/Ligare/

[j2salmingo]

Should be "lets", not "let's"

This paragraph seems quite dense. Starts with the builder pattern which already asks the questions of what is a builder and why/how to use it, so maybe it'd be nice to include an oversimplified definition of what it is first and why before linking to a Wikipedia article. Then, application modules is another dense definition... what can I put in here? And then ApplicationBuilder[T] being a FlaskApp would assume I know what generics are, and also asks the question of what other application types I can use and why it would be a FlaskApp here. As far as generics I think they are only mentioned as part of type hinting in Python so I'm not sure most Python users can figure this out.

A lot of the following paragraphs is "do thing, and run it, but you get an error or nothing happens" and I don't think that is satisfying from a tutorial standpoint. It might be better to have the completed code and then break it down instead of building it up. I think the API Endpoint part seems good from this perspective.

I'm a little confused at how you get from adding a method use_configuration, and that it takes a lambda using with_config_filename, especially because the error said I just need use_ssm or use_filename. Maybe you can link the documentation to where it requires that.

The last comment is that the Swagger UI being accessible at localhost:5000/ui kind of confuses me because, if I didn't specify it in the previous example with the endpoint, how did it know how to redirect there?

Thanks for reading my comment, hopefully I didn't sound too harsh since I know that writing documentation can be painful!

[aholmes]

A lot of the following paragraphs is "do thing, and run it, but you get an error or nothing happens" and I don't think that is satisfying from a tutorial standpoint. It might be better to have the completed code and then break it down instead of building it up. I think the API Endpoint part seems good from this perspective.

I've been hemming and hawing on this. I agree it's kind of annoying - each step you take is followed by "and here's yet another error to overcome." However, I don't want to dump a bunch of information and code when the goal is to break things down to build an application from scratch. To build an application from scratch successfully, you need to understand at least the bare minimum, which means knowing what errors to expect and why they are happening.

Maybe I can do something like put all the code and configuration up front, then demonstrate what happens when something specific is missing, and what it's for. This would lead to a shorter guide with the caveat that knowledge beyond rote copying requires intentionality and sticking through to the end of each page. Perhaps I can eliminate the error demonstration entirely by making the errors in-code more helpful.

I'm a little confused at how you get from adding a method ...

Yeah, this is an error on my part. I forgot to update the exception message. The cause and the fix are what the guide states, but the exception message references old code that no longer exists.

[aholmes]

The last comment is that the Swagger UI being accessible at localhost:5000/ui kind of confuses me because, if I didn't specify it in the previous example with the endpoint, how did it know how to redirect there?

Good question. :) I need to flesh this page out a bit more, and at least spell out that /ui is a default "endpoint" that is enabled for FlaskApp applications.

[j2salmingo]

I've been hemming and hawing on this. I agree it's kind of annoying - each step you take is followed by "and here's yet another error to overcome." However, I don't want to dump a bunch of information and code when the goal is to break things down to build an application from scratch. To build an application from scratch successfully, you need to understand at least the bare minimum, which means knowing what errors to expect and why they are happening.

I might have wrote that because I was looking at this earlier today:

https://docs.rs/clap/latest/clap/_derive/index.html

in which it starts with an example, and then breaks down each part.

FWIW, the documentation for this Rust crate has a reputation for being fairly obtuse, so in retrospect, I'm not sure if it's worth imitating.

Perhaps worth considering is the audience for this specific guide. This is for people who want to dig a little deeper and not have the scaffolder hold their hand. Perhaps they might be more comfortable with researching the other topics on their own?

I thought about this, are we expecting the audience to know these concepts? I am thinking back to last week's presentation where it was designed for researchers who might not be software engineering-inclined. But I also agree that it's not really the place to teach engineering concepts.

For gross oversimplification I am thinking along the lines of something like "we need an application so we use this application builder, where we can use methods to add modules and configurations. Then when we run the builder with build(), it gives us the application that we specified."

With generics, rather than explain generics or use generic type, you would specify that when you call ApplicationBuilder you tell it what kind of application to build, and you support Flask and FlaskApp application types, and you create it by ApplicationBuilderFlask . For those who want to dig deeper, they can click on the method signature to see the documentation behind it, and then if they do know generics, it'll be right there.

[aholmes]

in which it starts with an example, and then breaks down each part.

I looked through the Connexion docs a bit and found they hide some details in a collapsible area, e.g., "View a detailed reference of ..." https://connexion.readthedocs.io/en/stable/quickstart.html

It might work out to put the block of code -

from Ligare.web.application import ApplicationBuilder
from connexion import FlaskApp

application_builder = ApplicationBuilder[FlaskApp]()

application_builder.use_configuration(
    lambda config_builder: \
        config_builder.with_config_filename("app/config.toml")
)

result = application_builder.build()

result.run()

followed by something like ... (pretend these are collapsible areas)

Review what use_configuration is for >

Review how to get a result from a builder >

Review how to run a FlaskApp >

---

In the interim, how do these revisions look? https://uclahs-cds.github.io/Ligare/cookbook/web_applications/create-application-from-scratch/2-creating-the-application.html (from this workflow run https://github.com/uclahs-cds/Ligare/actions/runs/11923302150). With your additional suggestions, I'm thinking the conceptual explanations are still too technical, but it's closer to clarifying what's going on here.

[aholmes]

I thought about this, are we expecting the audience to know these concepts? I am thinking back to last week's presentation where it was designed for researchers who might not be software engineering-inclined.

It's a good question I'm still trying to figure out. At the moment, I think this document serves two purposes:

• Engineers who want the framework to get out of the way and need a starting point
• Anyone looking to connect concepts seen in a scaffolded application

Soon, I am going to have @dan-knight and @alkaZeltser work on creating new applications for their projects following these guidelines and will have a better idea of what helps move things along for them - the scaffolder with technical explanations, or just technical explanations.

Also @dan-knight and @alkaZeltser please feel free to contribute your thoughts regarding the documentation as well.