Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Automatic generation of docstrings from Quasar docs #112

Open
PGimenez opened this issue Oct 19, 2023 · 1 comment
Open

Automatic generation of docstrings from Quasar docs #112

PGimenez opened this issue Oct 19, 2023 · 1 comment
Assignees
Labels
enhancement New feature or request

Comments

@PGimenez
Copy link
Member

I've created a script that automatically generates docstrings for the StippleUI components from the quasar docs. Repository here: https://github.com/GenieFramework/StippleUIDocstringGen

The steps are:

  1. Extract component descriptions from the Quasar docs.
  2. Get Stipple usage examples from the component gallery
  3. Extract component parameters from the Quasar API. This gives the table that appears at the beginning of each component's page
  4. Put all three parts together in a markdown document

The result is something like this:

	 $(SIGNATURES)
The slider is a great way for the user to specify a number value between a minimum and maximum value, with optional steps between valid values. The slider also has a focus indicator (highlighted slider button), which allows for keyboard adjustments of the slider.

## Example
``julia
@app begin
    @in volume = 4
end

ui() = slider(1:1:10, :volume)
``

## Arguments
### behavior
  - `name::String` - Used to specify the name of the control; Useful if dealing with forms submitted directly to a URL
  - `snap::Boolean` - Snap on valid values, rather than sliding freely; Suggestion: use with 'step' prop
  - `reverse::Boolean` - Work in reverse (changes direction)
  - `vertical::Boolean` - Display in vertical direction

### content
  - `label::Boolean` - Popup a label when user clicks/taps on the slider thumb and moves it
  - `markers::Any["Boolean", "Number"]` - Display markers on the track, one for each possible value for the model or using a custom step (when specifying a Number)

This is the complete docstring that we'd have for each function in the SippleUI API. Now, the question is how to add it. We could simply add it in the source, or we could write some macro to include the docstring with something like

@doccomp slider
function slider(...)

What would you suggest @essenciary @hhaensel ?

Also, note that this would only replace the docstrings for components that are already in the gallery since these are the ones with usage examples.

Screenshot 2023-10-19 at 16 52 47
@PGimenez PGimenez added the enhancement New feature or request label Oct 19, 2023
@PGimenez PGimenez self-assigned this Oct 19, 2023
@hhaensel
Copy link
Member

That sounds like a big step forward for the docs!🚀

Actually, we could also extract examples from Quasar. Together with my parse_vue_html() we could most probably build decent examples, which would , however, require some manual steps.

I've just submitted a PR that supports Dicts and Vectors as values for arguments.
If that is in place, we can replace Object with Dict and Arraywith Vector.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants