From e602a472be60af2e6b015ce577ed64b076d5a2fd Mon Sep 17 00:00:00 2001 From: "Github Action (authored by pmalacho-mit)" Date: Sun, 4 Feb 2024 12:47:44 -0800 Subject: [PATCH] moved assets to documentation assets. documented doc generation process --- README.md | 2 +- {assets => documentation/assets}/addOns.gif | Bin {assets => documentation/assets}/hover.gif | Bin extensions/README.md | 87 +++++++++++++++--- extensions/documentation/README.md | 79 ++++++++++++++++ extensions/documentation/package.json | 5 +- .../documentation/scripts/generateREADME.ts | 5 +- .../src/customArguments/README.md | 2 +- .../documentation/src/tutorial/README.md | 2 +- 9 files changed, 161 insertions(+), 21 deletions(-) rename {assets => documentation/assets}/addOns.gif (100%) rename {assets => documentation/assets}/hover.gif (100%) create mode 100644 extensions/documentation/README.md diff --git a/README.md b/README.md index 0578c7d9b..2d4817adb 100644 --- a/README.md +++ b/README.md @@ -170,7 +170,7 @@ First, read through the documentation of the `index.ts` file (written inside of Also, try hovering over fields to view their documentation (typically a [summary](https://jsdoc.app/tags-summary.html), [examples](https://jsdoc.app/tags-example.html), and a [longer desrciption](https://jsdoc.app/tags-description.html)). -![Gif of video hovering over fields to peak documentation](/assets/hover.gif) +![Gif of video hovering over fields to peak documentation](/documentation/assets/hover.gif) Still stuck? Check out our [From 0 to Extension guide](#-from-0-to-extension) and/or contact more experienced extension developers, like [Parker](https://github.com/pmalacho-mit) or [Randi](https://github.com/randi-c-dubs) diff --git a/assets/addOns.gif b/documentation/assets/addOns.gif similarity index 100% rename from assets/addOns.gif rename to documentation/assets/addOns.gif diff --git a/assets/hover.gif b/documentation/assets/hover.gif similarity index 100% rename from assets/hover.gif rename to documentation/assets/hover.gif diff --git a/extensions/README.md b/extensions/README.md index 1efe2f558..184a71f3a 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -28,7 +28,7 @@ This document will be most helpful for people doing more complex development, li ## Anatomy of an Extension Directory > NOTE: This is a generated README section, so no edits you make to it in this file will be saved. -If you want to edit it, please go to [extensions/documentation/src/anatomy/README.md](documentation/src/anatomy/README.md) +If you want to edit it, please go to [extensions/documentation/src/anatomy/README.md](documentation/src/anatomy/README.md) ([See more](documentation/README.md)) Extensions are defined by all the files that appear in their associated directory, located within `/extensions/src/`. @@ -93,7 +93,7 @@ A great to start digging into the files that make up an Extension is to check ou ## Testing Extensions > NOTE: This is a generated README section, so no edits you make to it in this file will be saved. -If you want to edit it, please go to [extensions/documentation/src/testing/README.md](documentation/src/testing/README.md) +If you want to edit it, please go to [extensions/documentation/src/testing/README.md](documentation/src/testing/README.md) ([See more](documentation/README.md)) Writing tests is an important part of creating maintainable software. @@ -402,7 +402,7 @@ createTestSuite({ Extension, __dirname }, { ## Programming Tutorial > NOTE: This is a generated README section, so no edits you make to it in this file will be saved. -If you want to edit it, please go to [extensions/documentation/src/tutorial/README.md](documentation/src/tutorial/README.md) +If you want to edit it, please go to [extensions/documentation/src/tutorial/README.md](documentation/src/tutorial/README.md) ([See more](documentation/README.md)) **_(Work in progress)_** @@ -570,7 +570,7 @@ You do this by providing "add ons" as arguments, which come after the first `det Your code editor will help you see which "add ons" are available -- simply start to try to type after the first argument of the `extension` function, and suggestions (and documentation) will pop up. -![Gif of extension addOns being suggested](/assets/addOns.gif) +![Gif of extension addOns being suggested](/documentation/assets/addOns.gif) ### Putting it all together @@ -603,7 +603,7 @@ export default class Example extends BaseClass { ## Creating UI for Extensions > NOTE: This is a generated README section, so no edits you make to it in this file will be saved. -If you want to edit it, please go to [extensions/documentation/src/ui/README.md](documentation/src/ui/README.md) +If you want to edit it, please go to [extensions/documentation/src/ui/README.md](documentation/src/ui/README.md) ([See more](documentation/README.md)) To develop UI for your extension, we ask that you implement an interface that will be rendered in a [modal](https://blog.hubspot.com/website/modal-web-design#:~:text=What%20is%20a%20modal?) / pop-up. @@ -687,7 +687,7 @@ You can also create UI in order to accomplish custom arguments. Hop over to [Add ## Porting an Extension to use our Framework & Typescript > NOTE: This is a generated README section, so no edits you make to it in this file will be saved. -If you want to edit it, please go to [extensions/documentation/src/porting/README.md](documentation/src/porting/README.md) +If you want to edit it, please go to [extensions/documentation/src/porting/README.md](documentation/src/porting/README.md) ([See more](documentation/README.md)) *Want to move your vanilla-JS extension to our Typescript framework and reap the benefits of type safety and code generation?* **Great!** @@ -1132,7 +1132,7 @@ export default class SomeBlocks extends Extension NOTE: This is a generated README section, so no edits you make to it in this file will be saved. -If you want to edit it, please go to [extensions/documentation/src/saveLoad/README.md](documentation/src/saveLoad/README.md) +If you want to edit it, please go to [extensions/documentation/src/saveLoad/README.md](documentation/src/saveLoad/README.md) ([See more](documentation/README.md)) The Extension Framework allows you to easily save arbitrary data for an extension when an `.sb3` (Scratch 3 format) project is saved. @@ -1185,7 +1185,7 @@ export default class SaveLoadExample extends extension({ name }, "customSaveData ## App Inventor Cross-Compilation / Interoperability > NOTE: This is a generated README section, so no edits you make to it in this file will be saved. -If you want to edit it, please go to [extensions/documentation/src/appInventor/README.md](documentation/src/appInventor/README.md) +If you want to edit it, please go to [extensions/documentation/src/appInventor/README.md](documentation/src/appInventor/README.md) ([See more](documentation/README.md)) This effort is a work in progress and **_not_** ready to use. @@ -1227,7 +1227,7 @@ export default class extends extension({ name: "App Inventor Example", tags: ["P ## Making use of the Block Utility & Block ID > NOTE: This is a generated README section, so no edits you make to it in this file will be saved. -If you want to edit it, please go to [extensions/documentation/src/blockUtility/README.md](documentation/src/blockUtility/README.md) +If you want to edit it, please go to [extensions/documentation/src/blockUtility/README.md](documentation/src/blockUtility/README.md) ([See more](documentation/README.md)) The Scratch runtime will pass a `BlockUtility` object to every block method when it is executed. @@ -1260,7 +1260,7 @@ export default class extends extension({ name: "Block Utility example" }) { ## Adding Custom Arguments > NOTE: This is a generated README section, so no edits you make to it in this file will be saved. -If you want to edit it, please go to [extensions/documentation/src/customArguments/README.md](documentation/src/customArguments/README.md) +If you want to edit it, please go to [extensions/documentation/src/customArguments/README.md](documentation/src/customArguments/README.md) ([See more](documentation/README.md)) The Extension Framework allows us to do a lot of cool stuff that would be tricky or impossible to do if we were using the [default Scratch Extension workflow](). @@ -1357,7 +1357,66 @@ export default class ExtensionWithCustomArgument extends extension(details, "cus Then, we modify the UI (Svelte) component we created earlier to match our block function argument, like so: -Error! This snippet couldn't be located. Please contact the repo maintainer. +```ts + + +
+ + + +
+ + + +``` + +> Included links: +> * https://github.com/mitmedialab/prg-extension-boilerplate/tree/dev/extensions#creating-ui-for-extensions ### (Advanced) Architecture @@ -1414,7 +1473,7 @@ From there, the extension framework handles the rest: ## Extension Menu Tags / Categories > NOTE: This is a generated README section, so no edits you make to it in this file will be saved. -If you want to edit it, please go to [extensions/documentation/src/extensionMenuTags/README.md](documentation/src/extensionMenuTags/README.md) +If you want to edit it, please go to [extensions/documentation/src/extensionMenuTags/README.md](documentation/src/extensionMenuTags/README.md) ([See more](documentation/README.md)) Extensions can be associated with certain `tags` (or categories), which are visible in the [Extensions Menu](https://en.scratch-wiki.info/wiki/Extension#Adding_Extensions) and allow users to more easily find the extensions they are looking for. @@ -1439,7 +1498,7 @@ To add define new `tags`, add an additional string literal to the [Tag type](). # Adding inline images to the text of blocks > NOTE: This is a generated README section, so no edits you make to it in this file will be saved. -If you want to edit it, please go to [extensions/documentation/src/inlineImages/README.md](documentation/src/inlineImages/README.md) +If you want to edit it, please go to [extensions/documentation/src/inlineImages/README.md](documentation/src/inlineImages/README.md) ([See more](documentation/README.md)) As noted in [Scratch's extension documentation](https://github.com/scratchfoundation/scratch-vm/blob/develop/docs/extensions.md#adding-an-inline-image), Blocks support arguments that can display images inline within their text display. @@ -1492,7 +1551,7 @@ export default class ExampleExtensionWithInlineImages extends extension({ ## Reference > NOTE: This is a generated README section, so no edits you make to it in this file will be saved. -If you want to edit it, please go to [extensions/documentation/src/reference/README.md](documentation/src/reference/README.md) +If you want to edit it, please go to [extensions/documentation/src/reference/README.md](documentation/src/reference/README.md) ([See more](documentation/README.md)) ### How Everything Fits Together ```mermaid diff --git a/extensions/documentation/README.md b/extensions/documentation/README.md new file mode 100644 index 000000000..7ffddb2ed --- /dev/null +++ b/extensions/documentation/README.md @@ -0,0 +1,79 @@ +# extensions/Documentation + +This folder contains a custom solution for documentating aspects of the `extensions` codebase. It enables the following: + +- Define code snippets as seperate files and reference them in markdown + - This enables writing automated tests for the code snippets to ensure they stay in sync with the `extensions` API +- Stitch multiple `README.md` files together to create a single, comprehensive `README.md` at [extensions/README.md](../../extensions/README.md) + - This is convenient to split up large `README.md` files that can be difficult to navigate + +## At a Glance + +How this works is every folder inside of [extensions/documentation/src](./src/) is expected to have a `README.md` file. When the `generate` command is ran from this package (defined in the [package.json](./package.json)), it will collect all of these `README` files, parse and transform the content according to the constructs ("hooks") defined below, and concatenate them into a single `README.md` file, which is written to [extensions/README.md](../README.md). + +This `generate` command is automatically ran on `push` through a [github action](../../.github/workflows/generate-extension-docs.yml). + +## Documentation "Hooks" + +Below are the 'hooks' that we implement to control the content of the `README.md` files. Each is defined using markdown's [link syntax](https://www.markdownguide.org/basic-syntax/#links) (e.g. `[]()`) + +### Code Snippet + +#### Entire File + +Assuming you've defined your code in a file called `index.ts` (which is colocated with your `README.md` file) + +**`README.md`** +``` +Check out the code below! + +[](./index.ts) +``` + +#### Part of a File + +If you only want to render a portion of your code file in the markdown, you must make a few additions to both your code (which assume here to be defined in `index.ts`), and how you reference that code in your `README.md` (by making use of an `export` [URL search parameter](https://support.google.com/google-ads/answer/6277564?hl=en)). + +**`index.ts`** +```ts +import { codeSnippet } from "documentation"; + +export const myCodeSnippet = codeSnippet(); + +function someFunctionToInclude() { + // ... +} + +myCodeSnippet.end; +``` + +**`README.md`** +``` +Check out the code below (which will only include the lines in between the snippet's declaration and 'myCodeSnippet.end')! + +[](./index.ts?export=myCodeSnippet) +``` + +> **NOTE:** You could've chose any name for the exported variable (instead of `myCodeSnippet`). You just must ensure that you use the correct export in your `README.md`. For example, you'll find a lot of exported codeSnippet's with the name `x` since it's very easy to reference (`[](./index.ts?export=x)`) + +#### Testing Code Snippets + +### Ordering + +By default, all of the `README.md` files are concatenated together in an effectively random order (it's likely alphabetical according to directory name, but this isn't an explicit decision). + +Therefore, we enable you to specify the ordering you'd like for a given piece of documentation by using the following "hook", which **MUST** be defined at the very top of your `README.md`: + +``` +[](order=) +``` + +For example: + +``` +[](order=1) +``` + +The above will ensure your `README.md` appears first in the generated file (or at least with all of the other `README.md`s with an `order` of `1`). + +> NOTE: Decimals are supported, which can enable more fine-grained control. \ No newline at end of file diff --git a/extensions/documentation/package.json b/extensions/documentation/package.json index ff5b502c7..f717b0079 100644 --- a/extensions/documentation/package.json +++ b/extensions/documentation/package.json @@ -3,7 +3,8 @@ "version": "1.0.0", "description": "Helper for making documentation", "scripts": { - "generate": "npm run ts:node:extensions --prefix ../../ -- ./extensions/documentation/scripts/generateREADME.ts" + "ts:node": "npm run ts:node:extensions --prefix ../../", + "generate": "npm run ts:node -- ./extensions/documentation/scripts/generateREADME.ts" }, "author": "", "license": "ISC", @@ -11,4 +12,4 @@ "chalk": "^4.1.2", "es-module-lexer": "^1.1.0" } -} +} \ No newline at end of file diff --git a/extensions/documentation/scripts/generateREADME.ts b/extensions/documentation/scripts/generateREADME.ts index 3edc3d482..9eb485a3c 100644 --- a/extensions/documentation/scripts/generateREADME.ts +++ b/extensions/documentation/scripts/generateREADME.ts @@ -94,12 +94,13 @@ const sortEntries = (entries: Entries): OrderedEntries => { const addIsGeneratedWarning = (entries: OrderedEntries): OrderedEntries => { const warning = "\n> NOTE: This is a generated README section, so no edits you make to it in this file will be saved. \nIf you want to edit it, please go to "; - const repoURL = "mitmedialab/prg-extension-boilerplate/tree/dev"; + const documentationREADME = path.relative(extensionsRoot, path.join(documentationRoot, "README.md")); + const seeMore = `([See more](${documentationREADME}))` return entries.map(({ content, pathToREADME }) => { const lines = content.split("\n"); const relativeToDocumentation = path.relative(extensionsRoot, pathToREADME); const relativeToExtensions = path.join("extensions", path.relative(extensionsRoot, pathToREADME)); - lines.splice(1, 0, warning + `[${relativeToExtensions}](${relativeToDocumentation})`); + lines.splice(1, 0, warning + `[${relativeToExtensions}](${relativeToDocumentation}) ${seeMore}`); return { pathToREADME, content: lines.join("\n") } }); } diff --git a/extensions/documentation/src/customArguments/README.md b/extensions/documentation/src/customArguments/README.md index 7bdf3b140..c71f37643 100644 --- a/extensions/documentation/src/customArguments/README.md +++ b/extensions/documentation/src/customArguments/README.md @@ -39,7 +39,7 @@ When invoking the `@block` decorator function on our method that uses a custom a Then, we modify the UI (Svelte) component we created earlier to match our block function argument, like so: -[](./CustomArgument.svelte) +[](./MyArgUI.svelte) ### (Advanced) Architecture diff --git a/extensions/documentation/src/tutorial/README.md b/extensions/documentation/src/tutorial/README.md index 3d6e6d15e..b8b14aa16 100644 --- a/extensions/documentation/src/tutorial/README.md +++ b/extensions/documentation/src/tutorial/README.md @@ -69,7 +69,7 @@ You do this by providing "add ons" as arguments, which come after the first `det Your code editor will help you see which "add ons" are available -- simply start to try to type after the first argument of the `extension` function, and suggestions (and documentation) will pop up. -![Gif of extension addOns being suggested](/assets/addOns.gif) +![Gif of extension addOns being suggested](/documentation/assets/addOns.gif) ### Putting it all together