Skip to content

Commit

Permalink
feat(docs): add docs support
Browse files Browse the repository at this point in the history
add docs support

Signed-off-by: ysicing <[email protected]>
  • Loading branch information
ysicing committed Nov 28, 2023
1 parent 8714bfc commit 3394243
Show file tree
Hide file tree
Showing 13 changed files with 423 additions and 215 deletions.
10 changes: 10 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,13 @@ _output/
bin/
.task
.history

node_modules

package-lock.json

# docs site cache
docs/.vitepress/cache

# docs site build files
docs/.vitepress/dist
2 changes: 1 addition & 1 deletion cmd/root.go
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ func BuildRoot(f factory.Factory) *cobra.Command {
// Don't search for a plugin
default:
if err := excmd.HandlePluginCommand(pluginHandler, cmdPathPieces); err != nil {
fmt.Fprintf(os.Stdout, "Error: %v\n", err)
f.GetLog().Fatalf("executing plugin command: %s, failed: %v", cmdName, err)
os.Exit(1)
}
}
Expand Down
38 changes: 38 additions & 0 deletions docs/.vitepress/config.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
import { defineConfig } from 'vitepress'
import locales from './locales'

// https://vitepress.dev/reference/site-config
export default defineConfig({
title: "Quickon Cli",
description: "命令行",

locales: locales.locales,

lastUpdated: true,

themeConfig: {
search: {
provider: 'local',
options: {
locales: {
zh_CN: {
translations: {
button: {
buttonText: '搜索文档',
buttonAriaLabel: '搜索文档'
},
modal: {
noResultsText: '无法找到相关结果',
resetButtonTitle: '清除查询条件',
footer: {
selectText: '选择',
navigateText: '切换'
}
}
}
}
},
},
},
}
})
51 changes: 51 additions & 0 deletions docs/.vitepress/locales/en_US.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
import { createRequire } from 'module'
import { defineConfig } from 'vitepress'
import { generateSidebarChapter } from './side_bar.js'

const require = createRequire(import.meta.url)

const chapters = generateSidebarChapter('en_US', new Map([
['introduction', 'Introduction'],
]))

export default defineConfig({
lang: 'en-US',

description: 'A cli tool in Go.',

themeConfig: {
nav: nav(),

lastUpdatedText: 'Last updated at',

sidebar: chapters,

socialLinks: [
{ icon: 'github', link: 'https://github.com/easysoft/quickon_cli' },
],

editLink: {
pattern: 'https://github.com/easysoft/quickon_cli/edit/master/docs/:path',
text: 'Edit this page on GitHub'
},

outline: {
level: 'deep',
label: 'On this page',
},

}
})

function nav() {
return [
{ text: 'Home', link: '/' },
{ text: 'Configuration', link: '/configuration/configuration-reference' },
{
text: 'Download',
items: [
{ text: 'Open-source Edition', link: 'https://github.com/easysoft/quickon_cli/releases/' },
]
}
]
}
13 changes: 13 additions & 0 deletions docs/.vitepress/locales/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
import { defineConfig } from 'vitepress'
import en_US from './en_US'

export default defineConfig({
locales: {
root: {
label: 'English',
lang: en_US.lang,
themeConfig: en_US.themeConfig,
description: en_US.description
},
}
})
78 changes: 78 additions & 0 deletions docs/.vitepress/locales/side_bar.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
import directoryTree from 'directory-tree'
import fs from 'fs'
import metadataParser from 'markdown-yaml-metadata-parser'

function getMetadataFromDoc(path: string): { sidebarTitle?: string, sidebarOrder?: number } {
const fileContents = fs.readFileSync(path, 'utf8')

return metadataParser(fileContents).metadata
}

export function generateSidebarChapter(locale: string, chapterDirName: Map<string, string>): any[] {
if (chapterDirName.size < 1) {
console.error(chapterDirName)
throw new Error(`Could not genereate sidebar: chapterDirName is empty`)
}

var chapterPath = ''
var sidebar: any[] = []

for (const chapterDirKey of chapterDirName.keys()) {
if (locale !== 'en_US') {
chapterPath = `./${locale}/${chapterDirKey}`
} else {
chapterPath = `./${chapterDirKey}`
}

const tree = directoryTree(chapterPath)

if (!tree || !tree.children) {
console.error(tree)
throw new Error(`Could not genereate sidebar: invalid chapter at ${chapterPath}`)
}

let items: { sidebarOrder: number, text: string, link: string }[] = []

// Look into files in the chapter
for (const doc of tree.children) {
// make sure it's a .md file
if (doc.children || !doc.name.endsWith('.md'))
continue

const { sidebarOrder, sidebarTitle } = getMetadataFromDoc(doc.path)

if (!sidebarOrder)
throw new Error('Cannot find sidebarOrder in doc metadata: ' + doc.path)

if (!sidebarTitle)
throw new Error('Cannot find sidebarTitle in doc metadata: ' + doc.path)

if (chapterDirKey === 'introduction' && doc.name === '_dummy-index.md') {
// Override index page link
items.push({
sidebarOrder,
text: sidebarTitle,
link: '/' + (locale === 'en_US' ? '' : locale + '/')
})
} else {
items.push({
sidebarOrder,
text: sidebarTitle,
link: "/" + doc.path
})
}
}

items = items.sort((a, b) => a.sidebarOrder - b.sidebarOrder)

// remove dash and capitalize first character of each word as chapter title
const text = chapterDirName.get(chapterDirKey) || chapterDirKey.split('-').join(' ').replace(/\b\w/g, l => l.toUpperCase())
sidebar.push({
text,
collapsed: false,
items,
})
}

return sidebar
}
49 changes: 49 additions & 0 deletions docs/api-examples.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
outline: deep
---

# Runtime API Examples

This page demonstrates usage of some of the runtime APIs provided by VitePress.

The main `useData()` API can be used to access site, theme, and page data for the current page. It works in both `.md` and `.vue` files:

```md
<script setup>
import { useData } from 'vitepress'

const { theme, page, frontmatter } = useData()
</script>

## Results

### Theme Data
<pre>{{ theme }}</pre>

### Page Data
<pre>{{ page }}</pre>

### Page Frontmatter
<pre>{{ frontmatter }}</pre>
```

<script setup>
import { useData } from 'vitepress'

const { site, theme, page, frontmatter } = useData()
</script>

## Results

### Theme Data
<pre>{{ theme }}</pre>

### Page Data
<pre>{{ page }}</pre>

### Page Frontmatter
<pre>{{ frontmatter }}</pre>

## More

Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata).
Loading

0 comments on commit 3394243

Please sign in to comment.