From a7696b1ca6f552d912d6f3a088c54c662d36a414 Mon Sep 17 00:00:00 2001 From: Brenden Matthews Date: Fri, 30 Sep 2022 11:31:40 -0500 Subject: [PATCH] Refactor doc component, update doc docs. --- doc/README.md | 7 ++++++ doc/config_settings.yaml | 7 ++++++ doc/lua.yaml | 7 ++++++ doc/variables.yaml | 7 ++++++ web/components/Docs.tsx | 42 +++++++++++++++++++++++++++++++++ web/pages/config_settings.tsx | 37 ++++------------------------- web/pages/lua.tsx | 33 ++++---------------------- web/pages/variables.tsx | 37 ++++------------------------- web/utils/doc-utils.ts | 44 ++++++++--------------------------- 9 files changed, 92 insertions(+), 129 deletions(-) create mode 100644 web/components/Docs.tsx diff --git a/doc/README.md b/doc/README.md index 1599a32e..0a3dbbb5 100644 --- a/doc/README.md +++ b/doc/README.md @@ -10,6 +10,13 @@ The `desc` field within the docs can be formatted with markdown, however _do not_ include headings within the `desc` fields, as it will mess up the man page output. In markdown, headings begin with `#`. +The supported documentation fields are: + +* `name`: the name of the thing +* `desc`: a markdown-formatted description of the thing +* `args`: optional list of arguments +* `default`: an optional default value, if applicable + ## Updating docs The man page is based on [`man.md.j2`](man.md.j2) which is a Jinja2 template. diff --git a/doc/config_settings.yaml b/doc/config_settings.yaml index 1c21f200..99905e92 100644 --- a/doc/config_settings.yaml +++ b/doc/config_settings.yaml @@ -2,6 +2,13 @@ # # The `desc` field can be formatted with markdown, but please do not include # headings (lines beginning with `#`) in the `desc` field. +# +# The supported fields are: +# +# * `name`: the name of the thing +# * `desc`: a markdown-formatted description of the thing +# * `args`: optional list of arguments +# * `default`: an optional default value, if applicable --- - name: alignment desc: |- diff --git a/doc/lua.yaml b/doc/lua.yaml index 4e0113a7..d0cfdedd 100644 --- a/doc/lua.yaml +++ b/doc/lua.yaml @@ -2,6 +2,13 @@ # # The `desc` field can be formatted with markdown, but please do not include # headings (lines beginning with `#`) in the `desc` field. +# +# The supported fields are: +# +# * `name`: the name of the thing +# * `desc`: a markdown-formatted description of the thing +# * `args`: optional list of arguments +# * `default`: an optional default value, if applicable --- - name: cairo_font_extents_t:create() desc: |- diff --git a/doc/variables.yaml b/doc/variables.yaml index 9ff5dc87..a4a7885b 100644 --- a/doc/variables.yaml +++ b/doc/variables.yaml @@ -2,6 +2,13 @@ # # The `desc` field can be formatted with markdown, but please do not include # headings (lines beginning with `#`) in the `desc` field. +# +# The supported fields are: +# +# * `name`: the name of the thing +# * `desc`: a markdown-formatted description of the thing +# * `args`: optional list of arguments +# * `default`: an optional default value, if applicable --- - name: acpiacadapter desc: |- diff --git a/web/components/Docs.tsx b/web/components/Docs.tsx new file mode 100644 index 00000000..da74c22b --- /dev/null +++ b/web/components/Docs.tsx @@ -0,0 +1,42 @@ +import { Doc } from '../utils/doc-utils' +import { Link } from 'react-feather' + +export interface DocsProps { + docs: Doc[] +} + +export default function Docs({ docs }: DocsProps) { + return ( + <> + {docs.map((doc) => ( +
+
+
+ + + +
+
+ + {doc.name} + +
+ {doc.default && ( +
+ Default: {doc.default} +
+ )} +
+
+
+ ))} + + ) +} diff --git a/web/pages/config_settings.tsx b/web/pages/config_settings.tsx index 93c72cd8..2adbcf7f 100644 --- a/web/pages/config_settings.tsx +++ b/web/pages/config_settings.tsx @@ -1,10 +1,10 @@ import Layout from '../components/Layout' import SEO from '../components/SEO' -import { ConfigSetting, getConfigSettings } from '../utils/doc-utils' -import { Link } from 'react-feather' +import { Doc, getConfigSettings } from '../utils/doc-utils' +import Docs from '../components/Docs' export interface ConfigSettingsProps { - config_settings: ConfigSetting[] + config_settings: Doc[] } export default function ConfigSettings(props: ConfigSettingsProps) { @@ -19,36 +19,7 @@ export default function ConfigSettings(props: ConfigSettingsProps) {

Configuration settings

-
- {props.config_settings.map((cs) => ( -
-
-
- - - -
-
- - {cs.name} - -
-
- Default:{' '} - {cs.default ? {cs.default} : n/a} -
-
-
-
- ))} -
+ ) diff --git a/web/pages/lua.tsx b/web/pages/lua.tsx index 13425617..1513029a 100644 --- a/web/pages/lua.tsx +++ b/web/pages/lua.tsx @@ -1,10 +1,10 @@ import Layout from '../components/Layout' import SEO from '../components/SEO' -import { getLua, LuaDoc } from '../utils/doc-utils' -import { Link } from 'react-feather' +import { getLua, Doc } from '../utils/doc-utils' +import Docs from '../components/Docs' export interface LuaProps { - lua: LuaDoc[] + lua: Doc[] } export default function Lua(props: LuaProps) { @@ -15,32 +15,7 @@ export default function Lua(props: LuaProps) {

Lua API

-
- {props.lua.map((cs) => ( -
-
-
- - - -
-
- - {cs.name} - -
-
-
-
- ))} -
+ ) diff --git a/web/pages/variables.tsx b/web/pages/variables.tsx index 613d0306..c6a97f2b 100644 --- a/web/pages/variables.tsx +++ b/web/pages/variables.tsx @@ -1,10 +1,10 @@ import Layout from '../components/Layout' import SEO from '../components/SEO' -import { getVariables, Variable } from '../utils/doc-utils' -import { Link } from 'react-feather' +import { getVariables, Doc } from '../utils/doc-utils' +import Docs from '../components/Docs' export interface VariablesProps { - variables: Variable[] + variables: Doc[] } export default function Variables(props: VariablesProps) { @@ -18,36 +18,7 @@ export default function Variables(props: VariablesProps) {

Variables

-
- {props.variables.map((cs) => ( -
-
-
- - - -
-
- - {cs.name} - -
-
- Default:{' '} - {cs.default ? {cs.default} : n/a} -
-
-
-
- ))} -
+ ) diff --git a/web/utils/doc-utils.ts b/web/utils/doc-utils.ts index b204e1fd..c5cac4e2 100644 --- a/web/utils/doc-utils.ts +++ b/web/utils/doc-utils.ts @@ -9,57 +9,33 @@ import rehypeStringify from 'rehype-stringify' const DOC_PATH = path.join(process.cwd(), '..', 'doc') -export interface ConfigSetting { +export interface Doc { name: string desc: string default: string | undefined args: string[] } -export function getConfigSettings(): ConfigSetting[] { +function getDocumentation(source: string): Doc[] { const configSettingsFile = fs.readFileSync( - path.join(DOC_PATH, 'config_settings.yaml'), + path.join(DOC_PATH, source), 'utf-8' ) - const parsed = yaml.load(configSettingsFile.toString()) as ConfigSetting[] + const parsed = yaml.load(configSettingsFile.toString()) as Doc[] const docs = parsed.map((c) => ({ ...c, desc: processMarkdown(c.desc) })) return docs } -export interface Variable { - name: string - desc: string - default: string | undefined - args: string[] +export function getConfigSettings(): Doc[] { + return getDocumentation('config_settings.yaml') } -export function getVariables(): Variable[] { - const variablesFile = fs.readFileSync( - path.join(DOC_PATH, 'variables.yaml'), - 'utf-8' - ) - const parsed = yaml.load(variablesFile.toString()) as Variable[] - const docs = parsed.map((c) => ({ ...c, desc: processMarkdown(c.desc) })) - - return docs +export function getVariables(): Doc[] { + return getDocumentation('variables.yaml') } - -export interface LuaDoc { - name: string - desc: string - args: string[] -} - -export function getLua(): LuaDoc[] { - const variablesFile = fs.readFileSync( - path.join(DOC_PATH, 'lua.yaml'), - 'utf-8' - ) - const parsed = yaml.load(variablesFile.toString()) as LuaDoc[] - const docs = parsed.map((c) => ({ ...c, desc: processMarkdown(c.desc) })) - - return docs +export function getLua(): Doc[] { + return getDocumentation('lua.yaml') } function processMarkdown(input: string): string {