tauri-apps/tauri
1
1
Fork 0
mirror of https://github.com/tauri-apps/tauri.git synced 2024-09-17 11:17:28 +03:00
Code Issues Packages Projects Releases Wiki Activity

feat(docs): Generate json AST for js api. Remove docs related workflows. (#3335)

Browse Source 
* 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
This commit is contained in:
Fabian-Lars 2022-02-09 00:02:51 +01:00 committed by GitHub
parent 4ae5e34079
commit 617b397a7f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 11 additions and 636 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
.github/workflows/covector-version-or-publish.yml vendored
View File

@ -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

134
.github/workflows/update-docs.yml vendored
View File

@ -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.

26
.scripts/covector/generate-cli-doc.js
View File

@ -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)

147
.scripts/covector/generate-config-doc.js
View File

@ -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: `<Array type="${typeName}">\n${tab}${propertyEl}\n${previousTabLevel}</Array>`
})
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 `<Properties ${fields.join(' ')}/>`
}
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'))
)

104
.scripts/covector/templates/cli.md
View File

@ -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`
<Command name="info" />
{info}
It shows a concise list of information about the environment, Rust, Node.js and their versions as well as some relevant configurations.
<Alert title="Note" icon="info-alt">
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.
</Alert>
## `init`
<Command name="init" />
{init}
## `plugin init`
<Command name="plugin init" />
{plugin init}
## `dev`
<Command name="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.
<a href="/docs/api/config#build">See more about the configuration.</a><br/><br/>
<Alert title="Troubleshooting" type="warning" icon="alert">
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.
</Alert>
## `deps`
<Command name="deps" />
{deps}
## `build`
<Command name="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.
<a href="/docs/api/config#build">See more about the configuration.</a>
## `icon`
<Command name="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`
<Command name="--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).

103
.scripts/covector/templates/config.md
View File

@ -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 <a href="/docs/api/cli#tauri-init">here</a>) 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}
<!-- Dirty trick to have an anchor without make it appear in the table of contents -->
<div id="bootstrapper"></div>
<Alert title="bootstrapper script">
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.
</Alert>
```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'"
}
}
```

2
tooling/api/package.json
View File

@ -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",