Can I edit the docs? I’m in the process of learning Scriptable and maybe I just can read documentation, but I write a lot of Vue.js and find their docs so helpful, with examples and use cases.
Right now I wanted to get the calender items for today, so I opend the docs CalendarEvent - Scriptable Docs (in the app) and get the following
I had no idea how to use it, so I googled “scriptable today()” to go to this forum looking for an example. I would love an example in the docs looking something like:
// Get all calender items of today
const items = await CalendarEvent.today()
// Get only the Caledar items of calendar 'myCalendarName'
const myCalendar = ['myCalendarName']
const items = await CalendarEvent.today(myCalendar)
This is just an example, I’ve found that a lot of doc entries being like “Function X = Function X”, which is fine, but I love to help, so if I could send pull requests to the docs.
I’ve did a quick search on github, but couldn’t find anything
I don’t know the answer. But as someone with limited understanding of javascript, I would love to see more examples like you suggest in the documentation.
That said, I don’t know that I want development time taken away from the app itself. Contributions to the docs could be a great solution.
The official docs are not open source as far as I know—they’re maintained exclusively by Simon.
However, another user set up a site with Docusaurus 2 at https://scriptable-for-dummies.vercel.app. As the name implies, it’s intended to be more of a user-friendly guide with user-contributed pages than the rigid format of the official docs. We intended to populate it with lots of articles from community members, but we never really ended up doing anything with it–I think we just lost the flow of ideas for what to write. So it’s pretty much just an empty site at the moment.
If you’d like to contribute to that, please do! I’d love to get it to the point of being useful and then put it out there as a viable source of information. I’d be happy to start writing articles for it as well if it’s going to be useful.
Hey, I have been on GitHub for awhile and follow SimonStovring but have not seen any real part of scriptable as open source but over the past couple years a lot of people have taken the app to a new use level with lots of scripts they keep on GitHub as open source. yaylinda has several scripts and two are calendar scripts, not sure if they will help you. Must continue in second post…. I guess can only put two links in post
continued from earlier post…… supermamon always has an updated list of scripts for scriptable and the shortcuts from Apple. I’ve seen him on a lot of these sites and he’s always on top of what’s new and working.Probable the GitHub Repo to follow with the most is dersvenhesse. He was the first to start a curated awesome Repo for scriptable 9 months ago, and has done a very nice job. He probably has 30-40 scripts with great pics, all sorted out in his readme.md file. If anything you should check out his repo, I’m sure more people will see it and keep it flush with fresh scripts. Hope this helps and I did this reply correctly. Usually just read posts and have never added my two cents. Let me know if these links don’t post correctly. Alec
@ tf2 same here, let the developer do what they do best, but I would love to help writing the docs.
@FifiTheBulldog I see, it’s a good idea, but the docs are one click away when in the app, so getting users to some other site will always be a hassle.
@22940dev thanks, yeah these repos I found to really helpful to see how others used specific functions. And that is what I do right now: look at the docs fine a function and then search for that function to see how people have implemented them
That is what I would love from the docs and explanation of the function (what it is right now) and then some simple examples of how you could use them, you could than link to other sites like https://scriptable-for-dummies.vercel.app with a more in depth guide
I think it’s fair to say that @simonbs has probably thought through this question and concluded that opening the documentation isn’t going to happen.
The existing documentation is pretty good as far as it goes. I don’t think it makes sense to duplicate it.
What I’d like most — and what it sounds like others might want as well — is a sort of documentation-by-example library or cookbook.
What if we tried that? The goal would be to have one or more very simple examples of using different components. It could even include doing some basic things with Javascript that beginners might have trouble with (eg, it took me forever to figure out how to generate a YYYY-mm-dd format).
I don’t know if it makes the most sense to use the scriptable-for-dummies setup that already exists (which seems more like an attempt for a full documentation replacement), or to use GitHub’s wiki feature, or something else.
This is an example of what I’m thinking of (which I’m sure I found elsewhere and maybe adapted slightly) — a simple function to retrieve JSON from an iCloud file and use it.
function fetchJsonData() {
var fm = FileManager.iCloud();
var filedir = fm.documentsDirectory();
var filepath = filedir+"/filename.json";
var c = fm.readString(filepath);
let json = JSON.parse(c);
return json;
}
var myJsonData = await fetchJsonData();
And a more complex one: a very simple widget template that can be adapted to other purposes.
// Variables used by Scriptable.
// These must be at the very top of the file. Do not edit.
// icon-color: light-gray; icon-glyph: copy;
// This is a minimal Widget script template
// See Widget-HelloWorld.js for something slightly more interesting
// These are "asynchronous" functions, which is a fancy way of
// saying that they can take some time, and you need to wait
let myData = await loadData()
let widget = await createWidget(myData)
// If the script isn't running as a Widget,
// show a debugging preview of the widget,
// in Scriptable itself
if ( ! config.runsInWidget) {
await widget.presentMedium()
}
// Finalize widget for display on Home screen
// This is the "real" way to present a widget
Script.setWidget(widget)
Script.complete()
// End of script execution
///
/// Implementation functions
///
// "Slow" data loading function
async function loadData() {
// This function loads essential data, e.g., via web request
return 'Hello world'
}
// Widget creation, contents, layout, etc.
// This is all the "what goes inside" the widget.
async function createWidget(theMessage) {
// Create the widget object
let widget = new ListWidget()
widget.backgroundColor = new Color("#4a525a") // a nice gray
// Add content to the widget
// Flexible spacer above content to center it vertically
widget.addSpacer()
// Add a line of text
let titleTxt = widget.addText(theMessage)
titleTxt.font = Font.boldSystemFont(24)
titleTxt.textColor = new Color("#eeeeee") // almost white
// Flexible spacer below content to center it vertically
widget.addSpacer()
// Return the fully composed widget object to the main script
// The main script is responsible for actually presenting the widget
return widget
}
I have nothing but respect for Simon, his work and his ethos, and while there is certainly documentation for Scriptable, aspects of it are on the light side. That’s why many libraries include more detailed explanation and worked examples.
For example in the Drafts library I created pages (example) include simple worked examples for everything.
Yes, it is a lot more effort. Yes, it is worth it, people find it useful and can accomplish more with it. It especially helps those who are just starting out, or who are simply struggling with something a little more advanced.
Simon’s time may well be more productively focused on other things than creating another level of depth to the documentation, but I would argue that providing a near duplicate set of docs, with more detailed explanations and some inline examples would be hugely beneficial to many.
I think duplicating it, and enhancing it, would bring great benefit to the wider community.
Point taken. I wonder if it would be possible to get his permission to incorporate his documentation, and essentially annotate/extend it. The equivalent of forking it, as opposed to letting others add to or edit it directly
It uses a type file that @simonbs is kindly providing on https://docs.scriptable.app/scriptable.json. I think that he is fine with other people using it as well. With this you could compile the documentation yourself and add the things you want to add.
There might be some typos in it which I’ve fixed in my TypeScript definitions output, so you might also generate the docs from them. One advantage would also be that there are probably more tools to generate a documentation from TypeScript files than from the custom Tern definition file that Simon is providing.
I’ll start by saying that I really appreciate everyone’s willingness to contribute to the documentation. That’s heart warming
Scriptable’s documentation is not open source right now. While the documentation is ultimately just a bunch of Markdown files that could easily be open sourced, I’m generating these Markdown files from the Swift source code in the Scriptable project. That means I can just regenerate the documentation when I add a new API and the updated documentation would match the documentation in the Swift source code.
The in-app documentation, which is available while offline, the syntax definition for highlighting code and the auto-completion definition is also generated from the Swift source code.
If I were to open source the documentation there would be some non-trivial work required to make sure that these don’t get out of sync.
Another reason that the documentation isn’t open source is that it’ll require some other things from me that I don’t have capacity for right now. It’s truly great that people are willing to contribute to the documentation but once people start contributing, I should also make sure to send time aside for reviewing their changes, giving feedback and doing this in multiple iterations. I would love to have this flow and for everyone to contribute but I also need to be realistic and it’s not realistic for me to have capacity for that right now.
@simonbs thanks for the reply. And fair enough you should really focus on spending time how you want to spend it. Having the docs generate that way surely saves a lot of time and indeed reviewing pull request also takes time away, but I would say even that could be out sourced. There are probably a few dedicated Scriptable users who could e some sort of documentation moderators, they would be the only once who could allow pull requests. Then again the merging of the auto generated docs and manually typed docs need to get merged somehow.
Maybe it would be nice than to get the people who are already hosting examples and attempts at new docs to get together to brain storm some ideas on how to host a second ‘cookbook scriptable docs’ of some sort. I think it would make more sense to combine resources then to have multiple sources out there.
I certainly like the idea of collaborating on one community-run cookbook site. Based on what Simon said, it sounds like if community contributions to the documentation are going to happen, it’ll have to be to a third-party site unless the flow for generating the docs changes dramatically.
Have other users set up other alternative documentation sites like scriptable-for-dummies (I don’t know how I feel about that name, by the way)? I spend way more time on r/Scriptable on Reddit and Discord than I do on this forum, so I might be a bit out of the loop on what people have done here.
It is a lot of work – I should know, I’ve done it! The documentation for my database program (Panorama X) is also generated from structured comments in the source code. I built an automated system that allows customers to edit the Markdown and submit the changes, which then get automatically pushed back into the source code (since it is well structured, that is possible). It was definitely a significant project to implement, but ultimately well worth it – over the past 4 years users have submitted over 2,500 changes. I do review them all with a diff tool (Kaleidescope), but wind up accepting over 95% of them. It’s so much easier both for the customer and for me to get changes in this way, and everyone gets better documentation. Since it appears that you also have enthusiastic and knowledgable customers, I thought this data point might be of interest to you.
