From 06da99497b5d12bba710720bdc4d5cfa176c7cb1 Mon Sep 17 00:00:00 2001 From: GarboMuffin Date: Wed, 16 Aug 2023 23:20:36 -0500 Subject: [PATCH] Extension documentation tuning (#898) - downgrade scratchblocks until custom block arguments are fixed - tune some colors - add a proper header - fix spacing around horizontal lines - migrate away from using .html in docsURI --- CONTRIBUTING.md | 2 +- development/builder.js | 9 ++-- development/docs-template.ejs | 72 +++++++++++++++++++++++++----- development/render-docs.js | 4 +- docs/CST1229/zip.md | 2 +- extensions/CST1229/zip.js | 3 +- extensions/CubesterYT/TurboHook.js | 2 +- extensions/ar.js | 2 +- extensions/bitwise.js | 2 +- extensions/box2d.js | 2 +- extensions/local-storage.js | 2 +- package-lock.json | 10 ++--- package.json | 4 +- website/turbowarp.svg | 68 ++++++++++++++++++++++++++++ 14 files changed, 151 insertions(+), 33 deletions(-) create mode 100644 website/turbowarp.svg diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d2d5dc28b3..3967ac4389 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,7 +43,7 @@ To add an extension to the website homepage, modify [`website/index.ejs`](websit New extensions do not *need* images, but they are highly encouraged. Save the image in the `images` folder with the same folder name and file name (but different file extension) as the extension's source code. For example, if your extension is located in `extensions/TestMuffin/fetch.js`, save the image as `images/TestMuffin/fetch.svg` or `images/TestMuffin/fetch.png`. The homepage generator will detect it automatically. Images are displayed in a 2:1 aspect ratio. SVG (preferred), PNG, or JPG are accepted. PNG or JPG should be 600x300 in resolution. Please add proper attribution to `images/README.md` for *any* resources that were not made by you. -Most extensions shouldn't need external documentation -- it should be obvious what to do just by looking at the blocks. That said, some do need more explanation. Documentation is written in markdown and placed in the `docs` folder with a similar layout to images. For example, documentation for `extensions/TestMuffin/fetch.js` would be saved as `docs/TestMuffin/fetch.md`. Our version of markdown is slightly extended to allow rendering [scratchblocks](https://scratchblocks.github.io/). Just look at the existing documentation for examples. It's not a perfect experience: block colors have to be manually copied, and icons aren't supported, but it's better than what we had before. +Most extensions shouldn't need external documentation -- it should be obvious what to do just by looking at the blocks. That said, some do need more explanation. Documentation is written in markdown and placed in the `docs` folder with a similar layout to images. For example, documentation for `extensions/TestMuffin/fetch.js` would be saved as `docs/TestMuffin/fetch.md`. Our version of markdown is slightly extended to allow rendering [scratchblocks](https://scratchblocks.github.io/). Just look at the existing documentation for syntax examples. It's not a perfect experience: block colors have to be manually copied, and icons aren't supported, but it's better than what we had before. Once you put your markdown there, you can set a `docsURI` like `https://extensions.turbowarp.org/TestMuffin/fetch`. Static resources, such as example links, go in the `website` folder. This is where some example assets used by extensions such as fetch are placed. diff --git a/development/builder.js b/development/builder.js index 7b03ff6e22..a5613ecee1 100644 --- a/development/builder.js +++ b/development/builder.js @@ -145,14 +145,15 @@ IMAGE_FORMATS.set('.jpg', ImageFile); IMAGE_FORMATS.set('.svg', SVGFile); class DocsFile extends DiskFile { - constructor (path) { + constructor (path, extensionId) { super(path); + this.extensionId = extensionId; this.getDiskPath = null; } read () { const markdown = super.read().toString('utf-8'); - return renderDocs(markdown); + return renderDocs(markdown, this.extensionId); } getType () { @@ -234,10 +235,10 @@ class Builder { continue; } const extensionId = docsFilename.split('.')[0]; - build.files[`/${extensionId}.html`] = new DocsFile(path); + build.files[`/${extensionId}.html`] = new DocsFile(path, extensionId); } - const scratchblocksPath = pathUtil.join(__dirname, '../node_modules/@turbowarp/scratchblocks/build/scratchblocks.min.js'); + const scratchblocksPath = pathUtil.join(__dirname, '../node_modules/scratchblocks/build/scratchblocks.min.js'); build.files['/docs-internal/scratchblocks.js'] = new DiskFile(scratchblocksPath); const extensionFiles = []; diff --git a/development/docs-template.ejs b/development/docs-template.ejs index 5a31a49d5e..e2510f93b6 100644 --- a/development/docs-template.ejs +++ b/development/docs-template.ejs @@ -4,6 +4,7 @@ <%= headerText %> - TurboWarp Extension Documentation + -
+ + +

<%- headerHTML %>

@@ -106,13 +152,15 @@

TurboWarp is not affiliated with Scratch, the Scratch Team, or the Scratch Foundation.

-
+ - - + <% if (usesScratchBlocks) { %> + + + <% } %> diff --git a/development/render-docs.js b/development/render-docs.js index bd614c80a7..b882596354 100644 --- a/development/render-docs.js +++ b/development/render-docs.js @@ -23,9 +23,10 @@ md.renderer.rules.fence = function (tokens, idx, options, env, self) { /** * @param {string} markdownSource Markdown code + * @param {string} slug Path slug like 'TestMuffin/fetch' * @returns {string} HTML source code */ -const renderDocs = (markdownSource) => { +const renderDocs = (markdownSource, slug) => { const env = {}; const tokens = md.parse(markdownSource, env); @@ -50,6 +51,7 @@ const renderDocs = (markdownSource) => { const bodyHTML = md.renderer.render(tokens, md.options, env); return renderTemplate(path.join(__dirname, 'docs-template.ejs'), { + slug, headerHTML, headerText, bodyHTML, diff --git a/docs/CST1229/zip.md b/docs/CST1229/zip.md index 1d5cd49560..ef32c21961 100644 --- a/docs/CST1229/zip.md +++ b/docs/CST1229/zip.md @@ -14,7 +14,7 @@ Most blocks in this extension work with a path format: - A `/` at the end denotes a directory, like `folder/` - Multiple slashes in a row or trying to go above the root directory will result in an error (usually the block doing nothing or returning the empty value) -## Archive management blocks (link) +## Archive management blocks Blocks for creating and saving the current archive. Only one archive can be open at a time. diff --git a/extensions/CST1229/zip.js b/extensions/CST1229/zip.js index 07091f33d8..0ee8cca7d1 100644 --- a/extensions/CST1229/zip.js +++ b/extensions/CST1229/zip.js @@ -47,8 +47,7 @@ return { id: "cst1229zip", name: "Zip", - // docsURI: "http://localhost:8000/CST1229/zip.html", - docsURI: "https://extensions.turbowarp.org/CST1229/zip.html", + docsURI: "https://extensions.turbowarp.org/CST1229/zip", blockIconURI: extIcon, diff --git a/extensions/CubesterYT/TurboHook.js b/extensions/CubesterYT/TurboHook.js index 864b3c474c..d3d81cae59 100644 --- a/extensions/CubesterYT/TurboHook.js +++ b/extensions/CubesterYT/TurboHook.js @@ -21,7 +21,7 @@ color2: "#2f39a1", color3: "#28318f", menuIconURI: icon, - docsURI: "https://extensions.turbowarp.org/CubesterYT/TurboHook.html", + docsURI: "https://extensions.turbowarp.org/CubesterYT/TurboHook", blocks: [ { diff --git a/extensions/ar.js b/extensions/ar.js index ed507084e9..88d36e132d 100644 --- a/extensions/ar.js +++ b/extensions/ar.js @@ -484,7 +484,7 @@ color1: "#d10000", color2: "#bd0000", color3: "#af0100", - docsURI: "https://extensions.turbowarp.org/ar.html", + docsURI: "https://extensions.turbowarp.org/ar", blocks: [ { opcode: "enterAR", diff --git a/extensions/bitwise.js b/extensions/bitwise.js index 938e2180c1..7db593e79f 100644 --- a/extensions/bitwise.js +++ b/extensions/bitwise.js @@ -30,7 +30,7 @@ color1: '#17cde6', - docsURI: "https://extensions.turbowarp.org/bitwise.html", + docsURI: "https://extensions.turbowarp.org/bitwise", menuIconURI: icon, blocks: [ diff --git a/extensions/box2d.js b/extensions/box2d.js index 8c5f411dc2..9c2bd1eb63 100644 --- a/extensions/box2d.js +++ b/extensions/box2d.js @@ -12354,7 +12354,7 @@ default: "Physics", description: "Label for the Griffpatch extension category", }), - docsURI: "https://extensions.turbowarp.org/box2d.html", + docsURI: "https://extensions.turbowarp.org/box2d", menuIconURI: menuIconURI, blockIconURI: blockIconURI, blocks: [ diff --git a/extensions/local-storage.js b/extensions/local-storage.js index 4f85eb3410..563d12a7ee 100644 --- a/extensions/local-storage.js +++ b/extensions/local-storage.js @@ -67,7 +67,7 @@ return { id: 'localstorage', name: 'Local Storage', - docsURI: "https://extensions.turbowarp.org/local-storage.html", + docsURI: "https://extensions.turbowarp.org/local-storage", blocks: [ { opcode: 'setProjectId', diff --git a/package-lock.json b/package-lock.json index aaef705921..d7fafffc5f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -131,11 +131,6 @@ "fastq": "^1.6.0" } }, - "@turbowarp/scratchblocks": { - "version": "3.6.3", - "resolved": "https://registry.npmjs.org/@turbowarp/scratchblocks/-/scratchblocks-3.6.3.tgz", - "integrity": "sha512-KhP30VjqXfeY5Zlyts+uRM1js6J2gQyKzW7kHICvI1hGs808m85EYTTYkmNxRwYjdE9cCapeLy8Xf7IHr4lcuQ==" - }, "@turbowarp/types": { "version": "git+https://github.com/TurboWarp/types-tw.git#d62df1559786c318f22148919cde69a3e74f8f34", "from": "git+https://github.com/TurboWarp/types-tw.git#tw" @@ -1248,6 +1243,11 @@ "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==" }, + "scratchblocks": { + "version": "3.6.2", + "resolved": "https://registry.npmjs.org/scratchblocks/-/scratchblocks-3.6.2.tgz", + "integrity": "sha512-qiBGgolVBNlhR8QfDu/XA4LxRIPr0KD3BYLaRT238SjdRwalJwMMygaaLHQgJ4FiGgRK8gPHqoto/i1BYLs7nw==" + }, "send": { "version": "0.18.0", "resolved": "https://registry.npmjs.org/send/-/send-0.18.0.tgz", diff --git a/package.json b/package.json index b1b69d48dd..ca6eddd773 100644 --- a/package.json +++ b/package.json @@ -20,13 +20,13 @@ }, "homepage": "https://github.com/TurboWarp/extensions#readme", "dependencies": { - "@turbowarp/scratchblocks": "^3.6.3", "@turbowarp/types": "git+https://github.com/TurboWarp/types-tw.git#tw", "chokidar": "^3.5.3", "ejs": "^3.1.9", "express": "^4.18.2", "image-size": "^1.0.2", - "markdown-it": "^13.0.1" + "markdown-it": "^13.0.1", + "scratchblocks": "^3.6.2" }, "devDependencies": { "eslint": "^8.47.0" diff --git a/website/turbowarp.svg b/website/turbowarp.svg new file mode 100644 index 0000000000..6a1ec7f87d --- /dev/null +++ b/website/turbowarp.svg @@ -0,0 +1,68 @@ + +