mirror of
https://github.com/hashicorp/vault.git
synced 2026-05-12 08:06:59 +02:00
* removes doctoc, jsdoc-to-markdown and jsonlint packages and removes underscore version override * removes generate-docs script which uses removed docfy-md scipt Co-authored-by: Jordan Reimer <zofskeez@gmail.com>
This commit is contained in:
Vault Automation
GitHub
parent
825a0edc48
commit
e33118cee2
@ -1,8 +1,5 @@
|
||||
**Table of Contents**
|
||||
|
||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
|
||||
- [Vault UI](#vault-ui)
|
||||
- [Ember CLI Version Upgrade Matrix](#ember-cli-version-upgrade-matrix)
|
||||
- [Prerequisites](#prerequisites)
|
||||
@ -18,8 +15,6 @@
|
||||
- [Contributing / Best Practices](#contributing--best-practices)
|
||||
- [Further Reading / Useful Links](#further-reading--useful-links)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
# Vault UI
|
||||
|
||||
This README outlines the details of collaborating on this Ember application.
|
||||
|
||||
@ -1,23 +1,20 @@
|
||||
# CSS/SCSS
|
||||
|
||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
|
||||
- [Guidelines](#guidelines)
|
||||
- [Helper classes](#helper-classes)
|
||||
- [Core class styles](#core-class-styles)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
## Guidelines
|
||||
|
||||
- [**Helper classes**](#helper-classes) should be used if a styling block does not already exist and/or a reasonable number of helper classes can cover the desired style.
|
||||
- [**Core classes**](#core-class-styles) provide styling for any classes not associated with a component. The scope of each file is defined by the file name.
|
||||
- **Component specific styling** should only be added to, or created when you cannot achieve the styling with a helper class or core class.
|
||||
- **Utils'** files define mixins, and variables.
|
||||
- **Utils'** files define mixins, and variables.
|
||||
|
||||
> ### Known issues
|
||||
>
|
||||
> The following are known issues that we are working to address in conjunction with the adoption of HDS.
|
||||
>
|
||||
> 1. **Size variables** The UI does not follow a consistent size variable pattern. We use both px and rem to define font-size and we use px, rem, and ems to define margins, heights and widths. For accessibility reasons we _should_ define all font-sizing at the very least by rem, though this is not consistently done in the app.
|
||||
> 2. **Variable naming** The UI does not have a consistent pattern to variable naming. We use a mix of numbers and words (ex: `ui-gray-050` is the same as `ui-gray-lightest`).
|
||||
> 3. **Random variables** We have dieing but not dead variables. For example, we have some variables that define box-shadows and we have some variables to define animations, but we are missing many box-shadow definitions and we do not consistently use the animation variables.
|
||||
@ -26,7 +23,7 @@
|
||||
|
||||
### Helper classes
|
||||
|
||||
A good portion of our class definitions have come from Bulma. Bulma has since been removed, but we still rely on many of its class definitions. Bulma class definitions, specifically their helper classes, always end in the keyword `!important`. This use of `important!` and Bulma specific naming patterns has led to a mix of inconsistent helper class names. Moving forward, we have agreed as a team to pursue the following patterns. When it makes sense, please default to these instead of relying on existing helper names for guidance.
|
||||
A good portion of our class definitions have come from Bulma. Bulma has since been removed, but we still rely on many of its class definitions. Bulma class definitions, specifically their helper classes, always end in the keyword `!important`. This use of `important!` and Bulma specific naming patterns has led to a mix of inconsistent helper class names. Moving forward, we have agreed as a team to pursue the following patterns. When it makes sense, please default to these instead of relying on existing helper names for guidance.
|
||||
|
||||
- Drop the starting verb. Many of our helper classes start with a verb `has` or `is`. Going forward we prefer to drop the verb. `margin-bottom` instead of `is-margin-bottom`.
|
||||
- Start your helper class name with what the class controls. `margin-bottom` instead of `bottom-margin`.
|
||||
|
||||
@ -1,12 +1,7 @@
|
||||
# Forms
|
||||
|
||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
|
||||
- [Guidelines](#guidelines)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Render `FlashMessage` on success
|
||||
|
||||
@ -1,102 +0,0 @@
|
||||
---
|
||||
title: How to docfy
|
||||
order: 1
|
||||
---
|
||||
|
||||
# How to docfy
|
||||
|
||||
http://localhost:4200/ui/docs (navigate to directly or click the present icon in the bottom right of the app footer).
|
||||
|
||||
## `docs/` markdown files
|
||||
|
||||
Side nav links correspond to the file + directory structure within the `docs/` directory. These top-level markdown files **can** be edited directly and any updates should be saved and pushed to main. (Component docs are generated by the `pnpm docs` command, see below.)
|
||||
|
||||
## generating component docs
|
||||
|
||||
The `docs/components` directory is where _generated_ component markdown files are located after running `pnpm docs`. **Do not edit component markdown files directly**. Instead, update markdown by making changes to the `jsdoc` and then re-running the generate command. The `docs/components/*` files are included in `.gitignore` so they are not pushed to main. `jsdoc-to-markdown` errors log in the console.
|
||||
|
||||
> _If you have never run the `pnpm docs` command before, you need to create the `docs/components` directory locally before running `pnpm docfy-md` so the markdown has a place to go. `mkdir docs/components`_
|
||||
|
||||
```
|
||||
pnpm docfy-md <component name> <addon or engine> <full filepath>
|
||||
```
|
||||
|
||||
> _Note: the above command takes three args, if passing the full filepath for a component then the second arg is unnecessary_
|
||||
|
||||
| Command | Description |
|
||||
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| `pnpm docs` | generate markdown file for every\* component in the `addon/core` directory |
|
||||
| `pnpm docfy-md some-component-name` | generate markdown file for **specific** component |
|
||||
| `pnpm docfy-md read-more core` | generate markdown for `read-more` component in the `core` addon |
|
||||
| `pnpm docfy-md pki-test null ./lib/pki/addon/components/pki-key-usage.ts` | optional third arg is the full component filepath (first arg will become markdown file name) |
|
||||
| `mkdir docs/components` | create directory where the generated component markdown files will go |
|
||||
| `rm -f ./docs/components/*` | cleanup and delete generated component markdown files |
|
||||
|
||||
> _\*replication and `shamir/*` components are skipped as these are not reused and should eventually be moved outside the `addon/core` directory_
|
||||
|
||||
## Writing documentation for a component
|
||||
|
||||
Component docs are generated by the script `pnpm docs`. Accurate `jsdoc` syntax is important so `jsdoc-to-markdown` properly generates the markdown file for that component. **Do not edit component markdown files directly**.
|
||||
|
||||
| jsdoc examples | | |
|
||||
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| form-field (`@description` example) | [github ](https://github.com/hashicorp/vault/blob/main/ui/lib/core/addon/components/form-field.js) | [vscode ](../lib/core/addon/components/form-field.js) |
|
||||
| confirmation-modal | [github ](https://github.com/hashicorp/vault/blob/main/ui/lib/core/addon/components/confirmation-modal.js) | [vscode ](../lib/core/addon/components/confirmation-modal.js) |
|
||||
| certificate-card | [github ](https://github.com/hashicorp/vault/blob/main/ui/lib/core/addon/components/certificate-card.js) | [vscode ](../lib/core/addon/components/certificate-card.js) |
|
||||
| alert-inline (`@deprecated` example) | [github](https://github.com/hashicorp/vault/blob/main/ui/lib/core/addon/components/alert-inline.js) | [vscode ](../lib/core/addon/components/alert-inline.js) |
|
||||
| secret-list-header (code snippet only\*) | [github](https://github.com/hashicorp/vault/blob/main/ui/lib/core/addon/components/secret-list-header.js) | [vscode ](../lib/core/addon/components/secret-list-header.js) |
|
||||
|
||||
> _\*renders a template code snippet and not instantiated component because it relies on too many args that cannot be set up for component instance_
|
||||
|
||||
### Syntax tips
|
||||
|
||||
Docfy renders an actual instance of the component beneath `@example` as a sample. Make sure the component uses proper hbs syntax and all args are on a single line.
|
||||
|
||||
> - Check the generated markdown file for syntax errors or typos. To update the markdown, first edit the jsdoc then re-run the generator. _Do not edit component markdown files directly_
|
||||
> - Param types: `object`, `string`, `function`, `array`
|
||||
> - Do not include `null` for empty default values
|
||||
> - Wrap optional params in brackets `[]`
|
||||
> - To include a codeblock in your module's description use `@description`
|
||||
|
||||
```
|
||||
❌ multi-line jsdoc will not render a component example
|
||||
* @example
|
||||
* <Block
|
||||
* @title="Example"
|
||||
* @description="My component"
|
||||
* />
|
||||
```
|
||||
|
||||
```
|
||||
✅ this will render
|
||||
* @example
|
||||
* <Block @title="Example" description="My component" />
|
||||
```
|
||||
|
||||
**Template**
|
||||
|
||||
```
|
||||
/**
|
||||
* @module ComponentName
|
||||
* @description
|
||||
* Description of the component
|
||||
*
|
||||
* @example
|
||||
* <ComponentName @param={{}} optionalParam={{}} />
|
||||
*
|
||||
* @param {object} paramName - description
|
||||
* @param {array} requiredParam=foo - foo is the default value here
|
||||
* @param {function} [optionalParamName] - An optional parameter is wrapped in brackets
|
||||
* @param {string} [param="some default value"] - An optional parameter with a default value
|
||||
*/
|
||||
```
|
||||
|
||||
> ### Config
|
||||
>
|
||||
> - [docfy-md.js](../scripts/docfy-md.js): script that generates component markdown and passes options to `jsdoc2md` command
|
||||
> - [generate-docs.sh](../scripts/docfy-md.js): batch command that iterates over desired javascript and typescript file in the `core` addon engine
|
||||
> - [jsdoc2md.json](../jsdoc2md.json): `jsdoc-to-markdown` config file, necessary so typescript files can be passed to `docfy-md` script
|
||||
|
||||
### More info
|
||||
|
||||
- [Building and consuming components](./building-components.md)
|
||||
@ -1,8 +1,5 @@
|
||||
# Models
|
||||
|
||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
|
||||
- [Models](#models)
|
||||
- [Intro](#intro)
|
||||
- [Model patterns overview](#model-patterns-overview)
|
||||
@ -17,8 +14,6 @@
|
||||
- [Using Decorators](#using-decorators)
|
||||
- [@withFormFields()](#withformfields)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
## Intro
|
||||
|
||||
We use models primarily as the backing data layer for our forms and for our list/show views. As Ember-Data has matured, our patterns of usage have become outdated. This document serves to outline our current best-practices, since examples within the codebase are often out of date and do not always reflect our best practices or ambitions.
|
||||
|
||||
@ -1,16 +1,11 @@
|
||||
# Routing
|
||||
|
||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
|
||||
- [Guidelines](#guidelines)
|
||||
- [File structure](#file-structure)
|
||||
- [Shared functionality](#shared-functionality)
|
||||
- [Decorators](#decorators)
|
||||
- [@withConfirmLeave()](#withconfirmleave)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Parent route typically serves to group related child resources
|
||||
|
||||
@ -1,13 +1,8 @@
|
||||
# Serializers & Adapters
|
||||
|
||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
|
||||
- [Guidelines](#guidelines)
|
||||
- [Gotchas](#gotchas)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Prepend internal functions with an underscore to differentiate from Ember methods `_getUrl`
|
||||
|
||||
@ -79,7 +79,6 @@ const appConfig = {
|
||||
module.exports = function (defaults) {
|
||||
const app = new EmberApp(defaults, appConfig);
|
||||
|
||||
app.import('node_modules/jsonlint/lib/jsonlint.js');
|
||||
app.import('node_modules/text-encoder-lite/text-encoder-lite.js');
|
||||
app.import('vendor/jsondiffpatch.umd.js');
|
||||
app.import('vendor/htmlformatter.umd.js');
|
||||
|
||||
@ -13,8 +13,6 @@
|
||||
"build": "pnpm build:jsondiffpatch && ember build --environment=production && cp metadata.json ../http/web_ui/metadata.json",
|
||||
"build:dev": "pnpm build:jsondiffpatch && ember build",
|
||||
"build:jsondiffpatch": "webpack --config webpack.jsondiffpatch.config.js",
|
||||
"docs": "sh scripts/generate-docs.sh",
|
||||
"docfy-md": "node scripts/docfy-md.js",
|
||||
"lint:css": "stylelint \"**/*.css\"",
|
||||
"lint:css:fix": "pnpm lint:css --fix",
|
||||
"lint:fix": "concurrently -c \"auto\" -n lint: \"pnpm:lint:*:fix\"",
|
||||
@ -96,7 +94,6 @@
|
||||
"d3-shape": "~3.2.0",
|
||||
"date-fns": "~2.30.0",
|
||||
"date-fns-tz": "~1.3.8",
|
||||
"doctoc": "~2.2.1",
|
||||
"dompurify": "~3.2.5",
|
||||
"ember-a11y-testing": "~7.1.2",
|
||||
"ember-basic-dropdown": "~8.7.0",
|
||||
@ -149,9 +146,7 @@
|
||||
"execa": "^5.1.1",
|
||||
"filesize": "~4.2.1",
|
||||
"jsdoc-babel": "~0.5.0",
|
||||
"jsdoc-to-markdown": "~8.0.3",
|
||||
"jsondiffpatch": "0.7.3",
|
||||
"jsonlint": "~1.6.3",
|
||||
"lint-staged": "~16.0.0",
|
||||
"loader.js": "~4.7.0",
|
||||
"miragejs": "~0.1.48",
|
||||
@ -201,8 +196,7 @@
|
||||
"qs": "6.14.1",
|
||||
"rollup": "2.80.0",
|
||||
"serialize-javascript": "3.1.0",
|
||||
"socket.io": "4.8.1",
|
||||
"underscore": "1.13.7"
|
||||
"socket.io": "4.8.1"
|
||||
}
|
||||
},
|
||||
"engines": {
|
||||
|
||||
717
ui/pnpm-lock.yaml
generated
717
ui/pnpm-lock.yaml
generated
File diff suppressed because it is too large
Load Diff
@ -1,56 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Copyright IBM Corp. 2016, 2025
|
||||
* SPDX-License-Identifier: BUSL-1.1
|
||||
*/
|
||||
|
||||
/* eslint-disable */
|
||||
|
||||
/*
|
||||
run from the ui directory:
|
||||
pnpm docfy-md some-component
|
||||
|
||||
or if the docs are for a component in an in-repo-addon or an engine:
|
||||
pnpm docfy-md some-component name-of-engine
|
||||
|
||||
see the readme ui/docs/how-to-docfy.md for more info
|
||||
*/
|
||||
|
||||
const fs = require('fs');
|
||||
const jsdoc2md = require('jsdoc-to-markdown');
|
||||
|
||||
// the fullFilepath arg will override the assumed inputFile which is built using the addonOrEngine arg
|
||||
const [nameOrFile, addonOrEngine, fullFilepath] = process.argv.slice(2);
|
||||
|
||||
const isFile = nameOrFile.includes('.');
|
||||
const name = isFile ? nameOrFile?.split('.')[0] : nameOrFile; // can pass component-name or component-name.js
|
||||
const path = isFile ? nameOrFile : `${nameOrFile}.js`; // default to js
|
||||
|
||||
const inputFile = addonOrEngine ? `lib/${addonOrEngine}/addon/components/${path}` : `app/components/${path}`;
|
||||
const outputFile = `docs/components/${name}.md`;
|
||||
|
||||
const outputFormat = `
|
||||
{{#module}}
|
||||
# {{name}}
|
||||
{{>body}}
|
||||
{{/module}}
|
||||
`;
|
||||
|
||||
const options = {
|
||||
files: fullFilepath || inputFile,
|
||||
'example-lang': 'hbs preview-template',
|
||||
configure: './jsdoc2md.json',
|
||||
template: outputFormat,
|
||||
};
|
||||
|
||||
try {
|
||||
const md = jsdoc2md.renderSync(options);
|
||||
// for some reason components without a jsdoc @module doesn't throw, so throw manually
|
||||
if (md.includes('ERROR')) throw `${md} (there is probably no jsdoc for this component)`;
|
||||
fs.writeFileSync(outputFile, md);
|
||||
console.log(`✅ ${name}`);
|
||||
} catch (error) {
|
||||
console.log(`❌ ${name}`);
|
||||
console.log(error);
|
||||
}
|
||||
@ -1,22 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Copyright IBM Corp. 2016, 2025
|
||||
# SPDX-License-Identifier: BUSL-1.1
|
||||
|
||||
echo "Create components/ directory"
|
||||
mkdir docs/components/
|
||||
|
||||
echo "Generating markdown files for components in core addon..."
|
||||
|
||||
# iterate over every .ts and .js file in core/addon/components (including nested files)
|
||||
# skip .hbs files and shamir/ directory
|
||||
find "./lib/core/addon/components" -type f ! -name "*.hbs" -not -path "*/shamir*" -print0 | while IFS= read -r -d '' file; do
|
||||
component=`eval "echo $file | cut -d/ -f6"`;
|
||||
|
||||
# skip replication components
|
||||
if [[ "$component" == replication* ]]; then
|
||||
echo "🔃 skipping $component"
|
||||
continue
|
||||
fi
|
||||
|
||||
pnpm docfy-md $component core $file
|
||||
done
|
||||
Loading…
x
Reference in New Issue
Block a user