docs: 📝 add making a web app guide#69
Conversation
| ::: callout-note | ||
| If you are using [Template Data | ||
| Package](https://template-data-package.seedcase-project.org/) as a template for | ||
| your data package, follow the [guide](TODO:add/link) on enabling the request | ||
| feature there instead. The template automates running Propagate, generating the | ||
| request web app, and inserting it into the data package website. | ||
| ::: |
There was a problem hiding this comment.
I don't actually know if this is how it will work
| request web app, and inserting it into the data package website. | ||
| ::: | ||
|
|
||
| ## Building the web app |
There was a problem hiding this comment.
I'm using "build" in the titles because the command is build, but based on the discussion we started having about how exactly it will work under the hood, this may be misleading. For example, if actually all it does is copy the prebuilt web assets and datapackage.json into the output folder, then there's not much building there.
| The first argument can be any supported metadata format. See the [build command | ||
| design documentation](/docs/design/interface/cli.qmd#seedcase-propagate-build) | ||
| for details about supported formats. |
There was a problem hiding this comment.
Should I copy that over here?
There was a problem hiding this comment.
Maybe it would be clearer to say here that Propagate only supports datapackage.json for now?
| design documentation](/docs/design/interface/cli.qmd#seedcase-propagate-build) | ||
| for details about supported formats. | ||
|
|
||
| ## Previewing the web app |
|
|
||
| The web app will open automatically in your browser. | ||
|
|
||
| ## Publishing the web app |
There was a problem hiding this comment.
This is a best-guess workflow
There was a problem hiding this comment.
You could also add a callout block with a TODO link to the template data package and/or the data package guide here.
There was a problem hiding this comment.
We could also add more details about (or at least links to) how to publish the web app with Quarto, so this section becomes a bit more specific.
signekb
left a comment
signekb
left a comment
There was a problem hiding this comment.
Nice 👌 The last part in particular is also a bit unclear to me.
Some suggestions:
| The `build` command takes two inputs: | ||
|
|
||
| 1. The metadata file describing the data package. | ||
| 2. The output folder where the web app will be created. |
There was a problem hiding this comment.
| 2. The output folder where the web app will be created. | |
| 2. The output folder where the files for the web app will be created. |
| By default, `build` looks for a `datapackage.json` file in the current working | ||
| directory and creates the web app in `docs/requests/`. | ||
|
|
||
| To use the default arguments, open a terminal in the data package folder and |
There was a problem hiding this comment.
| To use the default arguments, open a terminal in the data package folder and | |
| To use the default arguments, open a terminal in the root of your data package folder (i.e., the folder with your metadata file) and |
| This reads the `datapackage.json` file and creates the files required for the | ||
| web app in the output directory. |
There was a problem hiding this comment.
We could remove this, since it's repeating what's already said on L27 and 28. But, maybe it's fine to keep it for clarity.
| This reads the `datapackage.json` file and creates the files required for the | |
| web app in the output directory. |
| The first argument can be any supported metadata format. See the [build command | ||
| design documentation](/docs/design/interface/cli.qmd#seedcase-propagate-build) | ||
| for details about supported formats. |
There was a problem hiding this comment.
Maybe it would be clearer to say here that Propagate only supports datapackage.json for now?
| Before publishing the web app, you can preview it locally using Propagate's | ||
| `preview` command. This starts a local web server that serves the generated app | ||
| so you can check that the request interface works as expected. |
There was a problem hiding this comment.
Ooo, this command should probably be added to the CLI design page then?
|
|
||
| The web app will open automatically in your browser. | ||
|
|
||
| ## Publishing the web app |
There was a problem hiding this comment.
You could also add a callout block with a TODO link to the template data package and/or the data package guide here.
| as a Quarto website, the generated files can be included in the website's source | ||
| files and published together with the rest of the site. | ||
|
|
||
| Copy the generated output folder into your website source while preserving its |
There was a problem hiding this comment.
Ideally, wouldn't the Owner have generated the files in the website source structure?
| where you place the generated folder and how your website is configured. | ||
|
|
||
| After publishing, Requesters can open the request page, select the data they | ||
| need, and create a request for a data subset. |
There was a problem hiding this comment.
Maybe add a TODO link to a guide describing this workflow?
| @@ -0,0 +1,94 @@ | |||
| --- | |||
| title: "Making a web app for a data package" | |||
| description: "How to use Propagate to create a web app for a data package." | |||
There was a problem hiding this comment.
| description: "How to use Propagate to create a web app for a data package." | |
| description: "How to use Propagate to create a web app for requesting subsets of a data package." |
|
|
||
| The web app will open automatically in your browser. | ||
|
|
||
| ## Publishing the web app |
There was a problem hiding this comment.
We could also add more details about (or at least links to) how to publish the web app with Quarto, so this section becomes a bit more specific.
joelostblom
left a comment
joelostblom
left a comment
There was a problem hiding this comment.
Looks good to me pending the existing comments!
3 participants
Description
This PR adds a guide for making a web app.
Closes #36
Needs a thorough review.
Checklist
just run-all