From 617b397a7f07dc376213c8f3d0bdaae45a5e33f6 Mon Sep 17 00:00:00 2001 From: Fabian-Lars Date: Wed, 9 Feb 2022 00:02:51 +0100 Subject: [PATCH] feat(docs): Generate json AST for js api. Remove docs related workflows. (#3335) * feat(docs): Generate json AST for js api * generate api.json in docs folder * remove doc workflows. add dispatch for tauri-docs * move cli/config doc generation to tauri-docs --- .../workflows/covector-version-or-publish.yml | 131 ++-------------- .github/workflows/update-docs.yml | 134 ---------------- .scripts/covector/generate-cli-doc.js | 26 ---- .scripts/covector/generate-config-doc.js | 147 ------------------ .scripts/covector/templates/cli.md | 104 ------------- .scripts/covector/templates/config.md | 103 ------------ tooling/api/package.json | 2 +- 7 files changed, 11 insertions(+), 636 deletions(-) delete mode 100644 .github/workflows/update-docs.yml delete mode 100644 .scripts/covector/generate-cli-doc.js delete mode 100644 .scripts/covector/generate-config-doc.js delete mode 100644 .scripts/covector/templates/cli.md delete mode 100644 .scripts/covector/templates/config.md diff --git a/.github/workflows/covector-version-or-publish.yml b/.github/workflows/covector-version-or-publish.yml index bd35188ea..1372c53ec 100644 --- a/.github/workflows/covector-version-or-publish.yml +++ b/.github/workflows/covector-version-or-publish.yml @@ -25,10 +25,10 @@ jobs: - uses: actions/setup-node@v2 with: node-version: 14 - registry-url: "https://registry.npmjs.org" + registry-url: 'https://registry.npmjs.org' cache: yarn cache-dependency-path: tooling/*/yarn.lock - + - name: Cache CLI cargo target uses: actions/cache@v2 with: @@ -60,7 +60,7 @@ jobs: CARGO_AUDIT_OPTIONS: ${{ secrets.CARGO_AUDIT_OPTIONS }} with: token: ${{ secrets.GITHUB_TOKEN }} - command: "version-or-publish" + command: 'version-or-publish' createRelease: true - name: Create Pull Request With Versions Bumped if: steps.covector.outputs.commandRan == 'version' @@ -69,125 +69,14 @@ jobs: token: ${{ secrets.GITHUB_TOKEN }} branch: release/version-updates title: Apply Version Updates From Current Changes - commit-message: "apply version updates" - labels: "version updates" + commit-message: 'apply version updates' + labels: 'version updates' body: ${{ steps.covector.outputs.change }} - update-docs: - needs: version-or-publish - if: needs.version-or-publish.outputs.successfulPublish == 'true' - runs-on: ubuntu-latest - steps: - # Setup - - name: checkout tauri - uses: actions/checkout@v2 - with: - path: tauri - - name: checkout tauri-docs - uses: actions/checkout@v2 - with: - repository: tauri-apps/tauri-docs - path: tauri-docs - - name: checkout tauri-search-bot - uses: actions/checkout@v2 - with: - repository: tauri-apps/tauri-search-bot - path: tauri-search-bot - - name: install webkit2gtk - run: | - sudo apt-get update - sudo apt-get install -y libgtk-3-dev webkit2gtk-4.0 libappindicator3-dev librsvg2-dev patchelf - - # Rust - - name: generate rust docs - working-directory: ./tauri/core/tauri - run: cargo doc --no-deps - - name: run rustdocusaurus - uses: tauri-apps/rustdocusaurus/github-action@v1.0.3 - with: - originPath: ./tauri/target/doc/ - targetPath: ./tauri-docs/docs/en/api/rust/ - sidebarPath: ./tauri-docs/sidebars/rustdoc.json - linksRoot: "" - cratesToProcess: "tauri" - - # TypeScript - - name: run typedocusaurus - uses: tauri-apps/typedocusaurus@v1 - with: - originPath: ./tauri/tooling/api/ - sidebarFile: ./tauri-docs/sidebars/typedoc.json - targetPath: ./tauri-docs/en/api/js/ - docusaurusPath: ./tauri-docs/ - - # Moving docs for Indexation - - name: copy docs - working-directory: ./tauri - run: | - mv docs/sidebar.json ${{ github.workspace }}/tauri-docs/sidebars/core.json - cp -r docs/!(.templates) ${{ github.workspace }}/tauri-docs/docs/en - mv ARCHITECTURE.md ${{ github.workspace }}/tauri-docs/docs/en/about/architecture.md - - # Indexing - - name: meilisearch indexation - uses: tauri-apps/docusaurus-meilisearch-indexer@v1 - with: - version: ${{ github.event.release.tag_name }} - docusaurusPath: ./tauri-docs - host: https://search.tauri.studio - apiKey: ${{ secrets.MEILISEARCH_APIKEY }} - docs: "Getting started,Usage,API" - - # Applying Version - - name: set docs' Tauri version - working-directory: ./tauri-docs - run: echo ${{ github.event.release.tag_name }} > version.txt - - name: set bot's Tauri version - working-directory: ./tauri-search-bot - run: echo ${{ github.event.release.tag_name }} > version.txt - - - uses: iamsauravsharma/create-dotenv@v1.1.0 - with: - directory: "./tauri-search-bot" - env: - ENV_KEY_DISCORD_BOT_SECRET: ${{ secrets.DISCORD_BOT_SECRET }} - ENV_KEY_PREFIX: \! - ENV_KEY_SITE: tauri.studio - ENV_KEY_ICON: https://i.imgur.com/UzDERvw.png - ENV_KEY_LIMIT: 5 - ENV_KEY_SEARCH_INDEX: ${{ github.event.release.tag_name }} - ENV_KEY_MEILISEARCH_PUBLIC_KEY: ea0105f56bb5a2111ed28c7a0c637fc0bed07273f571dc7cb1f73900e44f8e7f - - # Bot Deployment - - name: scp bot - uses: appleboy/scp-action@master - with: - host: ${{ secrets.DISCORD_BOT_HOST }} - username: ${{ secrets.DISCORD_BOT_SSH_USER }} - key: ${{ secrets.DISCORD_BOT_SSH_KEY }} - source: "./tauri-search-bot" - target: "~/tauri-search-bot" - - name: restart the bot - uses: appleboy/ssh-action@master - with: - host: ${{ secrets.DISCORD_BOT_HOST }} - username: ${{ secrets.DISCORD_BOT_SSH_USER }} - key: ${{ secrets.DISCORD_BOT_SSH_KEY }} - script: cd ~/tauri-search-bot && yarn && forever stopall && forever start ./src/index.js - - # tauri-docs PR - - name: git config - run: | - git config --global user.name "${{ github.event.pusher.name }}" - git config --global user.email "${{ github.event.pusher.email }}" - - name: create pull request for updated docs - uses: tauri-apps/create-pull-request@v3.4.1 + - name: Trigger doc update + if: steps.covector.outputs.successfulPublish == 'true' + uses: peter-evans/repository-dispatch@v1 with: token: ${{ secrets.TAURI_BOT_PAT }} - commit-message: "chore(docs): Update Rust & TS docs" - branch: docs/release - path: tauri-docs - title: Update Docs - labels: "new release" - body: | - These are the updated docs from the most recent release. + repository: tauri-apps/tauri-docs + event-type: update-docs diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml deleted file mode 100644 index 0c8fe520f..000000000 --- a/.github/workflows/update-docs.yml +++ /dev/null @@ -1,134 +0,0 @@ -# Copyright 2019-2021 Tauri Programme within The Commons Conservancy -# SPDX-License-Identifier: Apache-2.0 -# SPDX-License-Identifier: MIT - -name: update-docs - -on: - release: - types: [published] - workflow_dispatch: - inputs: - gitName: - description: "git name for PR" - required: false - default: "tauri-bot" - gitEmail: - description: "git email for PR" - required: false - default: "tauri-bot@tauri.studio" - version: - description: "Tauri version" - required: true - -jobs: - update-docs: - runs-on: ubuntu-latest - steps: - # Setup - - name: checkout tauri - uses: actions/checkout@v2 - with: - path: tauri - - name: checkout tauri-docs - uses: actions/checkout@v2 - with: - repository: tauri-apps/tauri-docs - path: tauri-docs - - name: checkout tauri-search-bot - uses: actions/checkout@v2 - with: - repository: tauri-apps/tauri-search-bot - path: tauri-search-bot - - # Any Rust documentation is currently disabled while we're falling back to docs.rs - - # - name: install webkit2gtk - # run: | - # sudo apt-get update - # sudo apt-get install -y libgtk-3-dev webkit2gtk-4.0 libappindicator3-dev librsvg2-dev patchelf - - # # Rust - # - name: generate rust docs - # working-directory: ./tauri/core/tauri - # run: cargo doc --no-deps - # - name: run rustdocusaurus - # uses: tauri-apps/rustdocusaurus/github-action@v1 - # with: - # originPath: ./tauri/target/doc/ - # targetPath: ./tauri-docs/docs/en/api/rust/ - # sidebarPath: "${{ github.workspace }}/tauri-docs/sidebars/rustdoc.json" - # linksRoot: "" - # cratesToProcess: "tauri" - - - name: Generate JS docs - working-directory: ./tauri/tooling/api - run: yarn && yarn generate-docs - - - name: Copy JS docs - run: cp -r tauri/tooling/api/docs/* tauri-docs/docs/api/js/ - - # Indexing - - name: meilisearch indexation - - uses: tauri-apps/docusaurus-meilisearch-indexer@v1 - with: - version: ${{ github.event.inputs.version || github.event.release.tag_name }} - docusaurusPath: "${{ github.workspace }}/tauri-docs" - host: https://search.tauri.studio - apiKey: ${{ secrets.MEILISEARCH_APIKEY }} - docs: "Getting started,Usage,API" - - # Applying Version - - name: set docs' Tauri version - working-directory: ./tauri-docs - run: echo ${{ github.event.inputs.version || github.event.release.tag_name }} > version.txt - - name: set bot's Tauri version - working-directory: ./tauri-search-bot - run: echo ${{ github.event.inputs.version || github.event.release.tag_name }} > version.txt - - - uses: iamsauravsharma/create-dotenv@v1.1.0 - with: - directory: './tauri-search-bot' - env: - ENV_KEY_DISCORD_BOT_SECRET: ${{ secrets.DISCORD_BOT_SECRET }} - ENV_KEY_PREFIX: \! - ENV_KEY_SITE: tauri.studio - ENV_KEY_ICON: https://i.imgur.com/UzDERvw.png - ENV_KEY_LIMIT: 5 - ENV_KEY_SEARCH_INDEX: ${{ github.event.release.tag_name }} - ENV_KEY_MEILISEARCH_PUBLIC_KEY: ea0105f56bb5a2111ed28c7a0c637fc0bed07273f571dc7cb1f73900e44f8e7f - - # Bot Deployment - - name: scp bot - uses: appleboy/scp-action@master - with: - host: ${{ secrets.DISCORD_BOT_HOST }} - username: ${{ secrets.DISCORD_BOT_SSH_USER }} - key: ${{ secrets.DISCORD_BOT_SSH_KEY }} - source: "${{ github.workspace }}/tauri-search-bot" - target: "~/tauri-search-bot" - - name: restart the bot - uses: appleboy/ssh-action@master - with: - host: ${{ secrets.DISCORD_BOT_HOST }} - username: ${{ secrets.DISCORD_BOT_SSH_USER }} - key: ${{ secrets.DISCORD_BOT_SSH_KEY }} - script: cd ~/tauri-search-bot/github/workspace/tauri-search-bot/ && yarn && forever stopall && forever start ./src/index.js - - # tauri-docs PR - - name: git config - run: | - git config --global user.name "${{ github.event.inputs.gitName }}" - git config --global user.email "${{ github.event.inputs.gitEmail }}" - - name: create pull request for updated docs - uses: tauri-apps/create-pull-request@v3.4.1 - with: - token: ${{ secrets.TAURI_BOT_PAT }} - commit-message: "chore(docs): Update Rust & TS docs" - branch: docs/release - path: tauri-docs - title: Update Docs - labels: "new release" - body: | - These are the updated docs from the most recent release. diff --git a/.scripts/covector/generate-cli-doc.js b/.scripts/covector/generate-cli-doc.js deleted file mode 100644 index 9b1afbba0..000000000 --- a/.scripts/covector/generate-cli-doc.js +++ /dev/null @@ -1,26 +0,0 @@ -const childProcess = require('child_process') -const path = require('path') -const fs = require('fs') -const rustCliPath = path.join( - __dirname, - '../../tooling/cli.rs/target/debug/cargo-tauri' -) -const templatePath = path.join(__dirname, '../../docs/.templates/cli.md') -const targetPath = path.join(__dirname, '../../docs/api/cli.md') -const template = fs.readFileSync(templatePath, 'utf8') - -const commands = ['info', 'init', 'plugin init', 'dev', 'build'] - -let doc = template - -for (const cmd of commands) { - const output = childProcess - .execSync(`${rustCliPath} ${cmd} --help`) - .toString() - .split('\n') - output.splice(0, 2) - output.splice(-1) - doc = doc.replace(`{${cmd}}`, '```\n' + output.join('\n') + '\n```') -} - -fs.writeFileSync(targetPath, doc) diff --git a/.scripts/covector/generate-config-doc.js b/.scripts/covector/generate-config-doc.js deleted file mode 100644 index 6e2de5a25..000000000 --- a/.scripts/covector/generate-config-doc.js +++ /dev/null @@ -1,147 +0,0 @@ -const fs = require('fs') -const path = require('path') -const schema = JSON.parse( - fs.readFileSync('tooling/cli.rs/schema.json').toString() -) -const templatePath = path.join(__dirname, '../../docs/.templates/config.md') -const targetPath = path.join(__dirname, '../../docs/api/config.md') -const template = fs.readFileSync(templatePath, 'utf8') - -function formatDescription(description) { - return description - ? description - .replace(/`/g, '\\`') - .replace(/\n/g, ' ') - .replace(/ /g, ' ') - .replace(/{/g, '\\{') - .replace(/}/g, '\\}') - : '' -} - -function generatePropertiesEl(schema, anchorRoot, definition, tab) { - const previousTabLevel = tab.replace(' ', '') - const fields = [`anchorRoot="${anchorRoot}"`] - - if (definition.additionalProperties) { - fields.push(`type="${definition.type}"`) - fields.push(`description="${formatDescription(definition.description)}"`) - } - - const rows = [] - for (const propertyName in definition.properties) { - const property = definition.properties[propertyName] - if ('type' in property) { - let type - if ('items' in property) { - if (property.items.type) { - type = `${property.items.type}[]` - } else { - const typeName = property.items.$ref.replace('#/definitions/', '') - const propDefinition = schema.definitions[typeName] - const propertyEl = generatePropertiesEl( - schema, - `${anchorRoot}.${propertyName}`, - propDefinition, - `${tab} ` - ) - rows.push({ - property: propertyName, - optional: 'default' in property || property.type.includes('null'), - type: `${typeName}[]`, - description: property.description, - child: `\n${tab}${propertyEl}\n${previousTabLevel}` - }) - continue - } - } else if (Array.isArray(property.type)) { - type = property.type.join(' | ') - } else { - type = property.type - } - rows.push({ - property: propertyName, - optional: true, - type, - description: property.description, - default: property.default - }) - } else if ('anyOf' in property) { - const subType = property.anyOf[0].$ref.replace('#/definitions/', '') - const propDefinition = schema.definitions[subType] - const propertyEl = generatePropertiesEl( - schema, - `${anchorRoot}.${propertyName}`, - propDefinition, - `${tab} ` - ) - rows.push({ - property: propertyName, - optional: - property.anyOf.length > 1 && property.anyOf[1].type === 'null', - type: subType, - description: property.description, - child: propertyEl - }) - } else if ('allOf' in property) { - const subType = property.allOf[0].$ref.replace('#/definitions/', '') - const propDefinition = schema.definitions[subType] - const propertyEl = propDefinition.properties - ? generatePropertiesEl( - schema, - `${anchorRoot}.${propertyName}`, - propDefinition, - `${tab} ` - ) - : undefined - rows.push({ - property: propertyName, - optional: 'default' in property, - type: property.type || subType, - description: property.description, - child: propertyEl - }) - } - } - - if (rows.length > 0) { - const serializedRows = rows - .map((row) => { - const fields = [ - `property: "${row.property}"`, - `optional: ${row.optional}`, - `type: "${row.type}"`, - `description: \`${formatDescription(row.description)}\`` - ] - if (row.child) { - fields.push(`child: ${row.child}`) - } - return `{ ${fields.join(', ')} },` - }) - .join(`\n${tab}`) - fields.push(`rows={[\n${tab}${serializedRows}\n${previousTabLevel}]}`) - } else { - fields.push('rows={[]}') - } - - return `` -} - -const output = [] - -for (const propertyName in schema.properties) { - const property = schema.properties[propertyName] - const definitionName = property.allOf[0].$ref.replace('#/definitions/', '') - const definition = schema.definitions[definitionName] - let contents = `## \`${propertyName}\`\n\n${generatePropertiesEl( - schema, - propertyName, - definition, - ' ' - )}` - output.push(contents) -} - -fs.writeFileSync( - targetPath, - template.replace('{properties}', output.join('\n\n')) -) diff --git a/.scripts/covector/templates/cli.md b/.scripts/covector/templates/cli.md deleted file mode 100644 index c52f397d3..000000000 --- a/.scripts/covector/templates/cli.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -id: cli -title: CLI ---- - -import Command from '@theme/Command' -import Alert from '@theme/Alert' - -The `cli.js` command line interface is composed in TypeScript and published as a JavaScript NPM. It offers the `deps` and the `icon` commands, and propagates other commands to `cli.rs`. - -## `info` - - - -{info} - -It shows a concise list of information about the environment, Rust, Node.js and their versions as well as some relevant configurations. - - -This command is pretty helpful when you need to have a quick overview of your application. When requesting some help, it can be useful that you share this report with us. - - -## `init` - - - -{init} - -## `plugin init` - - - -{plugin init} - -## `dev` - - - -{dev} - -This command will open the WebView in development mode. It makes use of the `build.devPath` property from your `src-tauri/tauri.conf.json` file. - -If you have entered a command to the `build.beforeDevCommand` property, this one will be executed before the `dev` command. - -See more about the configuration.

- - - -If you're not using `build.beforeDevCommand`, make sure your `build.devPath` is correct and, if using a development server, that it's started before using this command. - - -## `deps` - - - -{deps} - -## `build` - - - -{build} - -This command will bundle your application, either in production mode or debug mode if you used the `--debug` flag. It makes use of the `build.distDir` property from your `src-tauri/tauri.conf.json` file. - -If you have entered a command to the `build.beforeBuildCommand` property, this one will be executed before the `build` command. - -See more about the configuration. - -## `icon` - - - -``` - Description - Create all the icons you need for your Tauri app. - - Usage - $ tauri icon /path/to/icon.png - - Options - --help, -h Displays this message - --log, -l Logging [boolean] - --target, -t Target folder (default: 'src-tauri/icons') - --compression, -c Compression type [optipng|zopfli] - --ci Runs the script in CI mode -``` - -This command will generate a set of icons, based on the source icon you've entered. Note that the source icon must be 1240x1240 with transparency. - -## `version` - - - -``` - Description - Returns the current version of tauri -``` - -This command will show the current version of Tauri. - -## CLI usage - -See more about the usage through this [complete guide](/docs/development/integration). diff --git a/.scripts/covector/templates/config.md b/.scripts/covector/templates/config.md deleted file mode 100644 index 3d9d2391c..000000000 --- a/.scripts/covector/templates/config.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Configuration ---- - -import Properties from '@theme/Properties' -import Array from '@theme/Array' -import Alert from '@theme/Alert' - -The `tauri.conf.json` is a file generated by the `tauri init` command (see here) that lives in your Tauri application source directory (src-tauri). - -Once generated, you may modify it at will to customize your Tauri application. - -# Platform-specific configuration - -In addition to the JSON defined on the `tauri.conf.json` file, Tauri reads a platform-specific configuration on `tauri.linux.conf.json`, `tauri.windows.conf.json` and `tauri.macos.conf.json` and merges it with the main `tauri.conf.json` configuration. - -# Configuration structure - -`tauri.conf.json` is composed of the following properties: - -{properties} - - -
- - -Instead of launching the app directly, we configure the bundled app to run a script that tries to expose the environment variables to the app; without that you'll have trouble using system CLI apps like Node.js. - - -```js title=Example -"tauri": { - "cli": { - "description": "Tauri communication example", - "longDescription": null, - "beforeHelp": null, - "afterHelp": null, - "args": [{ - "short": "c", - "name": "config", - "takesValue": true, - "description": "Config path" - }, { - "short": "t", - "name": "theme", - "takesValue": true, - "description": "App theme", - "possibleValues": ["light", "dark", "system"] - }, { - "short": "v", - "name": "verbose", - "multipleOccurrences": true, - "description": "Verbosity level" - }], - "subcommands": { - "update": { - "description": "Updates the app", - "longDescription": null, - "beforeHelp": null, - "afterHelp": null, - "args": [{ - "short": "b", - "name": "background", - "description": "Update in background" - }], - "subcommands": null - } - } - }, - "bundle": { - "active": true, - "targets": ["deb"], - "identifier": "com.tauri.dev", - "icon": ["icons/32x32.png", "icons/128x128.png", "icons/128x128@2x.png", "icons/icon.icns", "icons/icon.ico"], - "resources": [], - "externalBin": [], - "copyright": "", - "category": "DeveloperTool", - "shortDescription": "", - "longDescription": "", - "deb": { - "depends": [] - }, - "macOS": { - "frameworks": [], - "minimumSystemVersion": "", - "exceptionDomain": "" - } - }, - "allowlist": { - "all": true - }, - "windows": [{ - "title": "Tauri App", - "width": 800, - "height": 600, - "resizable": true, - "fullscreen": false - }], - "security": { - "csp": "default-src blob: data: filesystem: ws: wss: http: https: tauri: 'unsafe-eval' 'unsafe-inline' 'self'" - } -} -``` diff --git a/tooling/api/package.json b/tooling/api/package.json index 10021e941..207d50a94 100644 --- a/tooling/api/package.json +++ b/tooling/api/package.json @@ -19,7 +19,7 @@ "lint:lockfile": "lockfile-lint --path yarn.lock --type yarn --validate-https --allowed-hosts npm yarn", "format": "prettier --write --end-of-line=auto \"./**/*.{cjs,js,jsx,ts,tsx,html,css,json}\" --ignore-path .gitignore", "format:check": "prettier --check --end-of-line=auto \"./**/*.{cjs,js,jsx,ts,tsx,html,css,json}\" --ignore-path .gitignore", - "generate-docs": "typedoc src --githubPages false --readme none --entryDocument index.md --hideInPageTOC true" + "generate-docs": "typedoc src --githubPages false --readme none --entryDocument index.md --hideInPageTOC true --out docs --json docs/js-api.json --pretty false" }, "repository": { "type": "git",