From 4f62befb8aa059bcc0f3d102e7f0a813c3f5aecd Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Wed, 11 Aug 2021 22:18:33 -0400 Subject: [PATCH 01/15] Add docs and update README --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/workflows/docs.yml | 22 +- .github/workflows/go-docs.yml | 14 + README.md | 427 +---------------------------- docs/CNAME | 1 + docs/README.md | 3 + docs/about.md | 45 +++ docs/assets/default-monochrome.svg | 1 + docs/assets/favicon.ico | Bin 0 -> 15406 bytes docs/ignore.md | 77 ++++++ docs/index.md | 47 ++++ docs/installation.md | 80 ++++++ docs/overrides/main.html | 23 ++ docs/requirements.txt | 9 + docs/rules.md | 63 +++++ docs/tools.md | 6 + docs/usage.md | 253 +++++++++++++++++ mkdocs.yml | 102 +++++++ 18 files changed, 746 insertions(+), 429 deletions(-) create mode 100644 .github/workflows/go-docs.yml create mode 100644 docs/CNAME create mode 100644 docs/README.md create mode 100644 docs/about.md create mode 100644 docs/assets/default-monochrome.svg create mode 100644 docs/assets/favicon.ico create mode 100644 docs/ignore.md create mode 100644 docs/index.md create mode 100644 docs/installation.md create mode 100644 docs/overrides/main.html create mode 100644 docs/requirements.txt create mode 100644 docs/rules.md create mode 100644 docs/tools.md create mode 100644 docs/usage.md create mode 100644 mkdocs.yml diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 61cd5849..e6384701 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,7 +2,7 @@ - [ ] The commit message follows our [guidelines](https://github.com/get-woke/woke/blob/main/CONTRIBUTING.md) - [ ] Tests for the changes have been added (for bug fixes / features) -- [ ] Docs have been added / updated (for bug fixes / features) +- [ ] Docs have been added / updated (for bug fixes / features) see [docs/README.md](https://github.com/get-woke/woke/blob/main/docs/README.md) **What kind of change does this PR introduce?** (Bug fix, feature, docs update, ...) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 213d5785..55658d13 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,14 +1,20 @@ -name: Documentation refresh +name: Update mkdocs page on: push: - tags: - - v* - + # branches: [ main ] + branches: [ docs ] + paths: + - "docs/**" + - mkdocs.yml + - .github/workflows/docs.yml jobs: - docs: - name: Renew documentation + deploy: runs-on: ubuntu-latest steps: - - name: Pull new module version - uses: andrewslotin/go-proxy-pull-action@v1.0.2 + - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + with: + python-version: 3.x + - run: pip install -r docs/requirements.txt + - run: mkdocs gh-deploy --force diff --git a/.github/workflows/go-docs.yml b/.github/workflows/go-docs.yml new file mode 100644 index 00000000..213d5785 --- /dev/null +++ b/.github/workflows/go-docs.yml @@ -0,0 +1,14 @@ +name: Documentation refresh + +on: + push: + tags: + - v* + +jobs: + docs: + name: Renew documentation + runs-on: ubuntu-latest + steps: + - name: Pull new module version + uses: andrewslotin/go-proxy-pull-action@v1.0.2 diff --git a/README.md b/README.md index 61955bd6..be2af707 100644 --- a/README.md +++ b/README.md @@ -36,439 +36,26 @@ Companies like [GitHub](https://github.com/github/renaming), [Twitter](https://t ![woke.gif](https://raw.githubusercontent.com/get-woke/get-woke.github.io/main/img/woke.gif) -**Table of Contents** +## Install `woke` -- [Installation](#installation) - - [macOS](#macos) - - [Windows](#windows) - - [Simple installation](#simple-installation) - - [Build from source](#build-from-source) - - [Releases](#releases) - - [Docker](#docker) -- [Usage](#usage) - - [File globs](#file-globs) - - [STDIN](#stdin) - - [Output](#output) - - [Rules](#rules) - - [Options](#options) - - [Disabling Default Rules](#disabling-default-rules) - - [Ignoring](#ignoring) - - [Files](#files) - - [`.wokeignore`](#wokeignore) - - [In-line ignoring](#in-line-ignoring) - - [Exit Code](#exit-code) - - [Parallelism](#parallelism) -- [Tools](#tools) -- [Who uses `woke`](#who-uses-woke) -- [Resources](#resources) -- [Contributing](#contributing) -- [Versioning](#versioning) -- [Authors](#authors) -- [Acknowledgments](#acknowledgments) -- [License](#license) +- [On my machine](https://docs.getwoke.tech/installation); +- [On CI/CD systems](https://docs.getwoke.tech/installation/#ci). -## Installation +## Documentation -### macOS - -You can install a binary release on macOS using [brew](https://brew.sh) - -```bash -brew install get-woke/tap/woke -brew upgrade get-woke/tap/woke -``` - -### Windows - -You can install `woke` with [`scoop`](https://scoop.sh/) - -```sh -scoop bucket add get-woke https://github.com/get-woke/scoop-bucket.git -scoop install get-woke/woke -``` - -### Simple installation - -To install the latest version: - -```bash -curl -sSfL https://git.io/getwoke | \ - bash -s -- -b /usr/local/bin -``` - -Or install a specific version (omit the minor or patch portion to install the latest major/minor version) - -```bash -curl -sSfL https://git.io/getwoke | \ - bash -s -- -b /usr/local/bin v0.9.0 -``` - -Feel free to change the path from `/usr/local/bin`, just make sure `woke` -is available on your `$PATH` (check with `woke --version`). - -### Build from source - -Install the go toolchain: - -```bash -go get -u github.com/get-woke/woke -``` - -`woke` will be installed to `$GOPATH/bin/woke`. - -### Releases - -Download the latest binary from [Releases](https://github.com/get-woke/woke/releases/latest) - -### Docker - -You can run `woke` within docker. You will need to mount a volume that contains your source code and/or rules. - -```bash -## Run with all defaults, within the mounted /src directory -docker run -v $(pwd):/src -w /src getwoke/woke - -## Provide rules config -docker run -v $(pwd):/src -w /src getwoke/woke \ - woke -c my-rules.yaml -``` - -## Usage - -```text -$ woke --help - -woke is a linter that will check your source code for usage of non-inclusive -language and provide suggestions for alternatives. Rules can be customized -to suit your needs. - -Provide a list file globs for files you'd like to check. - -Usage: - woke [globs ...] [flags] - -Flags: - -c, --config string Config file (default is .woke.yaml in current directory, or $HOME) - --debug Enable debug logging - --exit-1-on-failure Exit with exit code 1 on failures - -h, --help help for woke - --no-ignore Ignored files in .gitignore, .ignore, .wokeignore, .git/info/exclude, and inline ignores are processed - -o, --output string Output type [text,simple,github-actions,json,sonarqube] (default "text") - --stdin Read from stdin - -v, --version version for woke -``` - -### File globs - -By default, `woke` will run against all text files in your current directory. -To change this, supply a space-separated list of globs as the first argument. - -This can be something like `**/*.go`, or a space-separated list of filenames. - -```bash -$ woke test.txt -test.txt:2:2-11: `Blacklist` may be insensitive, use `denylist`, `blocklist` instead (warning) -* Blacklist - ^ -test.txt:3:2-12: `White-list` may be insensitive, use `allowlist` instead (warning) -* White-list - ^ -test.txt:4:2-11: `whitelist` may be insensitive, use `allowlist` instead (warning) -* whitelist - ^ -test.txt:5:2-11: `blacklist` may be insensitive, use `denylist`, `blocklist` instead (warning) -* blacklist - ^ -``` - -### STDIN - -You can also provide text to `woke` via STDIN (Standard Input) - -```bash -$ echo "This has whitelist from stdin" | woke --stdin -/dev/stdin:1:9-18: `whitelist` may be insensitive, use `allowlist` instead (warning) -This has whitelist from stdin - ^ -``` - -This option may not be used at the same time as [File Globs](#file-globs) - -### Output - -Options for output include text (default), simple, json, github-actions, or sonarqube format. The following fields are supported, depending on format: - -| Field | Description | -| ------------ | ------------ | -| filepath | Relative path to file including filename | -| rulename | Name of the rule from the config file | -| termname | Specific term that was found in the text | -| alternative | List of alternative terms to use instead | -| note | Note about reasoning for inclusion | -| severity | From config, one of "error", "warning", or "info" | -| optionbool | Option value, true or false | -| linecontents | Contents of the line with finding | -| lineno | Line number, 1 based | -| startcol | Starting column number, 0 based | -| endcol | Ending column number, 0 based | -| description | Description of finding | - -Output is sent to STDOUT (Standard Output), which may be redirected to a file to save the results of a scan. - -#### text - -text is the default output format for woke. Displays each result on two lines. Includes color formatting if the terminal supports it. - -Structure: - -``` -::-: () - -``` - -#### simple - -simple is a format similar to text, but without color support and with each result on a single line. - -Structure: - -``` -::: -``` - -#### github-actions - -The github-actions output type is intended for integration with [GitHub Actions](https://github.com/features/actions). See [woke-action](https://github.com/get-woke/woke-action) for more information on integration. - -Structure: - -``` -:: file=,line=,col=:: -``` - -#### json - -Outputs the results as a series of [json](https://www.json.org/json-en.html) formatted structures, one per line. In order to parse as a JSON document, each line must be processed separately. This output type includes every field available in woke. - -Structure: - -``` -{"Filename":"","Results":[{"Rule":{"Name":"","Terms":["",...],"Alternatives":["",...],"Note":"","Severity":"","Options":{"WordBoundary":,"WordBoundaryStart":,"WordBoundaryEnd":,"IncludeNote":}},"Finding":"","Line":"","StartPosition":{"Filename":"","Offset":0,"Line":,"Column":},"EndPosition":{"Filename":"","Offset":0,"Line":,"Column":},"Reason":""}]} -``` - -#### sonarqube - -Format used to populate results into the popular [SonarQube](https://www.sonarqube.org/) code quality tool. Note: woke is not executed as part of SonarQube itself, so must be run and the results file output prior to execution. Typically woke would be executed with an automation server such as Jenkins, Travis CI or Github Actions prior to creating the SonarQube report. For details on the file format, see [Generic Issue Input Format](https://docs.sonarqube.org/latest/analysis/generic-issue/). The [Analysis Parameter](https://docs.sonarqube.org/latest/analysis/analysis-parameters/) `sonar.externalIssuesReportPaths` is used to point to the path to the report file generated by woke. - -Structure: - -``` -{"issues":[{"engineId":"woke","ruleId":"","primaryLocation":{"message":"","filePath":"","textRange":{"startLine":,"startColumn":,"endColumn":}},"type":"CODE_SMELL","severity":""} -]} -``` - -_Note: sonarqubeseverity is mapped from severity, such that an error in woke is translated to a MAJOR, warning to a MINOR, and info to INFO_ - -### Rules - -Configure your custom rules config in `.woke.yaml` or `.woke.yml`. `woke` uses the following precedence order. Each item takes precedence over the item below it: - -- `current working directory` -- `$HOME` - -This file will be picked up automatically up your customizations without needing to supply it with the `-c` flag. - -See [example.yaml](https://github.com/get-woke/woke/blob/main/example.yaml) for an example of adding custom rules. -You can also supply your own rules with `-c path/to/rules.yaml` if you want to handle different rulesets. - -The syntax for rules is very basic. You just need a name, a list of terms to match that violate the rule, -and a list of alternative suggestions. - -```yaml -rules: - - name: whitelist - terms: - - whitelist - - white-list - alternatives: - - allowlist - note: An optional description why these terms are not inclusive. It can be optionally included in the output message. - # options: - # word_boundary: false - # word_boundary_start: false - # word_boundary_end: false - # include_note: false -``` - -A set of default rules is provided in [`pkg/rule/default.yaml`](https://github.com/get-woke/woke/blob/main/pkg/rule/default.yaml). - -**NOTE: if you copy these rules into your config file, be sure to put them under the `rules:` key.** - -#### Options - -You can configure options for each rule. Add an `options` key to your rule definition to customize. - -Current options include: - -- `word_boundary` (default: `false`) - - If `true`, terms will trigger findings when they are surrounded by ASCII word boundaries. - - If `false`, will trigger findings if the term if found anywhere in the line, regardless if it is within an ASCII word boundary. - - **NOTE** setting this to true will always win out over `word_boundary_start` and `word_boundary_end` -- `word_boundary_start` (default: `false`) - - If `true`, terms will trigger findings when they begin with an ASCII word boundaries. - - If `false`, will trigger findings if the term if found anywhere in the line, regardless if it begins with an ASCII word boundary. -- `word_boundary_end` (default: `false`) - - If `true`, terms will trigger findings when they end with an ASCII word boundaries. - - If `false`, will trigger findings if the term if found anywhere in the line, regardless if it ends with an ASCII word boundary. -- `include_note` (default: `not set`) - - If `true`, the rule note will be included in the output message explaining why this finding is not inclusive - - If `false`, the rule note will not be included in the output message - - If `not set`, `include_note` in your `woke` config file (ie `.woke.yml`) regulates if the note should be included in the output message (default: `false`). - -#### Disabling Default Rules - -You can disable default rules by providing a rule in your `woke` config file (ie `.woke.yml`), with no terms or alternatives. - -This will disable the default `whitelist` rule: - -```yaml -rules: - - name: whitelist -``` - -### Ignoring - -#### Files - -You can ignore files by adding to your config file. All ways of ignoring files below should follow the [gitignore](https://git-scm.com/docs/gitignore) convention. - -```yaml -ignore_files: - - .git/* - - other/files/in/repo - - globs/too/* -``` - -`woke` will also automatically ignore anything listed in `.gitignore`, `.ignore`, and `.git/info/exclude`. - -#### `.wokeignore` - -You may also specify a `.wokeignore` file at the root of the directory to add additional ignore files. -This also follows the [gitignore](https://git-scm.com/docs/gitignore) convention. - -See [.wokeignore.example](.wokeignore.example) for a collection of common files and directories that may contain generated [SHA](https://en.wikipedia.org/wiki/Secure_Hash_Algorithms) and [GUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)s. Dependency directories are also shown in the example as the linter will parse dependency source code and possibly find errors. - -#### In-line and next-line ignoring - -There may be times where you don't want to ignore an entire file. -You may ignore a specific line for one or more rules by creating an in-line or next-line comment. - -This functionality is very rudimentary, it does a simple search for the phrase. Since -`woke` is just a text file analyzer, it has no concept of the comment syntax for every file -type it might encounter. - -For in-line ignoring, simply add the following to the line you wish to ignore, using comment syntax that is supported for your file type. -(`woke` is not responsible for broken code due to in-line ignoring. Make sure you comment correctly!) - -Next-line ignoring works in a similar way. Instead of adding to the end of line you wish to ignore, you can create the ignore comment on its own line just before it. Any alphanumeric text to the left of the phrase will cause `woke` to treat it as an in-line ignore, but any text to the right of the phrase will not be considered. -(Note: next-line ignore comments takes precedence over in-line ignores, so try to only use one for any given line!) - -```bash -This line has RULE_NAME but will be ignored # wokeignore:rule=RULE_NAME - -# wokeignore:rule=RULENAME -Here is another line with RULE_NAME that will be ignored - -# a couple of examples ignoring the following line for the whitelist rule -whitelist # wokeignore:rule=whitelist - -# wokeignore:rule=whitelist -whitelist - -# a couple of examples doing the same for multiple rules -# rule names must be comma-separated with no spaces -whitelist and blacklist # wokeignore:rule=whitelist,blacklist - -# wokeignore:rule=whitelist,blacklist -whitelist and blacklist - -# wokeignore:rule=whitelist text here won't be considered by woke even if it contains whitelist -this line with whitelist will still be ignored -``` - -Here's an example in go: - -```go -func main() { - fmt.Println("here is the whitelist") // wokeignore:rule=whitelist - - // wokeignore:rule=blacklist - fmt.Println("and here is the blacklist") -} -``` - -### Exit Code - -By default, `woke` will exit with a successful exit code when there are any rule failures. -The idea is, if you run `woke` on PRs, you may not want to block a merge, but you do -want to inform the author that they can make better word choices. - -If you're using `woke` on PRs, you can choose to enforce these rules with a non-zero -exit code by running `woke --exit-1-on-failure`. - -### Parallelism - -By default, `woke` will parse files in parallel and will consume as many resources as it can, unbounded. -This means `woke` will be fast, but might run out of memory, depending on how large the files/lines are. - -We can limit these allocations by bounding the number of files read in parallel. To accomplish this, -set the environment variable `WORKER_POOL_COUNT` to an integer value of the fixed number of goroutines -you would like to spawn for reading files. - -Read more about go's concurrency patterns [here](https://blog.golang.org/pipelines). - -## Tools - -- [GitHub Action](https://github.com/marketplace/actions/run-woke) -- [GitHub Action (reviewdog)](https://github.com/marketplace/actions/run-woke-with-reviewdog) -- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=get-woke.vscode-woke) - -## Who uses `woke` - -Are you using `woke` in your org? We'd love to know! Please send a PR and add your organization name/link to this list. - -- [Rent the Runway](https://www.renttherunway.com) ([blog post](https://dresscode.renttherunway.com/blog/woke)) -- [Veue](https://veuelive.com) -- [Cisco](https://ciscotechblog.com/blog/inclusive-infrastructure/) - -## Resources - -- -- -- -- +Documentation is hosted at . ## Contributing Please read [CONTRIBUTING.md](https://github.com/get-woke/woke/blob/main/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us. -## Versioning - -We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/get-woke/woke/tags). +![GitHub contributors](https://img.shields.io/github/contributors/get-woke/woke) ## Authors - **Caitlin Elfring** - [caitlinelfring](https://github.com/caitlinelfring) - - -## Acknowledgments - -The following projects provided inspiration for parts of `woke` - -- -- -- +See also the list of [contributors](https://github.com/get-woke/woke/contributors) who have participated in this project. ## License diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 00000000..3f2fb833 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +docs.getwoke.tech diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..0ecf0d66 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,3 @@ +# Woke documentation site + +TODO diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 00000000..10760aa5 --- /dev/null +++ b/docs/about.md @@ -0,0 +1,45 @@ +# About + +## Resources + +Below are some additional resources relating to why this project is important. + +- +- +- +- + +## Who uses `woke`? + +Are you using `woke` in your org? We'd love to know! Please send a PR and add your organization name/link to this list. + +- [Rent the Runway](https://www.renttherunway.com) ([blog post](https://dresscode.renttherunway.com/blog/woke)) +- [Veue](https://veuelive.com) +- [Cisco](https://ciscotechblog.com/blog/inclusive-infrastructure/) + +## Contributing + +Please read [CONTRIBUTING.md]({{config.repo_url}}blob/main/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us. + +## Versioning + +We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/get-woke/woke/tags). + +## Authors + +- **Caitlin Elfring** - [caitlinelfring](https://github.com/caitlinelfring) + + + +## Acknowledgments + +The following projects provided inspiration for parts of `woke` + +- +- +- + +## License + +This application is licensed under the MIT License, you may obtain a copy of it +[here](LICENSE). diff --git a/docs/assets/default-monochrome.svg b/docs/assets/default-monochrome.svg new file mode 100644 index 00000000..46d82d3b --- /dev/null +++ b/docs/assets/default-monochrome.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/assets/favicon.ico b/docs/assets/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..336e38090e77f0855217f4fecdf20e19c49cc255 GIT binary patch literal 15406 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 +woke logo +

{{ config.site_description }}

+

+ + +[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/get-woke/woke?logo=github&sort=semver)]({{config.repo_url}}releases) +[![GitHub All Releases](https://img.shields.io/github/downloads/get-woke/woke/total)]({{config.repo_url}}releases) +[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)]({{config.repo_url}}blob/main/LICENSE) +[![codecov](https://codecov.io/gh/get-woke/woke/branch/main/graph/badge.svg?token=BP133BM3HP)](https://codecov.io/gh/get-woke/woke/branch/main) +[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fget-woke%2Fwoke.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fget-woke%2Fwoke?ref=badge_shield) +[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#other-software) + +--- + +## About + +Creating an inclusive work environment is imperative to a healthy, supportive, and +productive culture, and an environment where everyone feels welcome and included. + +`woke` is a text file analysis tool that finds places within your source code that contain +non-inclusive language and suggests replacing them with more inclusive alternatives. + +Companies like [GitHub](https://github.com/github/renaming), [Twitter](https://twitter.com/TwitterEng/status/1278733303508418560), and [Apple](https://developer.apple.com/news/?id=1o9zxsxl) are actively supporting a move to inclusive language. + +## Demo + +![woke.gif](https://raw.githubusercontent.com/get-woke/get-woke.github.io/main/img/woke.gif) + +## Authors + +- **Caitlin Elfring** - [caitlinelfring](https://github.com/caitlinelfring) + +See also the list of [contributors]({{config.repo_url}}contributors) who participated in this project. + +## Contributing + +Please read [CONTRIBUTING.md]({{config.repo_url}}blob/main/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us. + +## License + +This application is licensed under the MIT License, you may obtain a copy of it +[here]({{config.repo_url}}blob/main/LICENSE). + +[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fget-woke%2Fwoke.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fget-woke%2Fwoke?ref=badge_large) diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..2b600b44 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,80 @@ +# Installation + +!!! tip + There are multiple ways to install `woke`. If you're interested in any installation methods + that are not listed here, feel free to open an [issue]({{config.repo_url}}issues). + +## Releases + +Download the latest binary from [Releases]({{config.repo_url}}releases/latest) + +## macOS + +You can install a binary release on macOS using [brew](https://brew.sh) + +```bash +brew install get-woke/tap/woke +brew upgrade get-woke/tap/woke +``` + +## Windows + +You can install `woke` with [`scoop`](https://scoop.sh/) + +```sh +scoop bucket add get-woke https://github.com/get-woke/scoop-bucket.git +scoop install get-woke/woke +``` + +## Simple installation + +To install the latest version: + +```bash +curl -sSfL https://git.io/getwoke | \ + bash -s -- -b /usr/local/bin +``` + +Or install a specific version (omit the minor or patch portion to install the latest major/minor version) + +```bash +curl -sSfL https://git.io/getwoke | \ + bash -s -- -b /usr/local/bin v0.9.0 +``` + +Feel free to change the path from `/usr/local/bin`, just make sure `woke` +is available on your `$PATH` (check with `woke --version`). + +## Build from source + +Install the go toolchain: + +```bash +go get -u github.com/get-woke/woke +``` + +`woke` will be installed to `$GOPATH/bin/woke`. + +## Docker + +You can run `woke` within docker. You will need to mount a volume that contains your source code and/or rules. + +```bash +## Run with all defaults, within the mounted /src directory +docker run -v $(pwd):/src -w /src getwoke/woke + +## Provide rules config +docker run -v $(pwd):/src -w /src getwoke/woke \ + woke -c my-rules.yaml +``` + +## CI + +### GitHub Actions + +- [GitHub Action](https://github.com/marketplace/actions/run-woke) +- [GitHub Action (reviewdog)](https://github.com/marketplace/actions/run-woke-with-reviewdog) + +### Others + +Are there other CI systems that you're using to run `woke`? Edit this page and add documentation/configurations for others. diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 00000000..02d156a4 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,23 @@ +{% extends "base.html" %} + +{% block extrahead %} + {% set title = config.site_name %} + {% if page and page.meta and page.meta.title %} + {% set title = title ~ " - " ~ page.meta.title %} + {% elif page and page.title and not page.is_homepage %} + {% set title = title ~ " - " ~ page.title | striptags %} + {% endif %} + + + + + + + + + + + + + +{% endblock %} diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..c1c9c81d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,9 @@ +# python requirements for docs +# https://www.mkdocs.org/ +# https://squidfunk.github.io/mkdocs-material/ +mkdocs +mkdocs-material +fontawesome-markdown +markdown-include +pymdown-extensions +mkdocs-macros-plugin diff --git a/docs/rules.md b/docs/rules.md new file mode 100644 index 00000000..ae393237 --- /dev/null +++ b/docs/rules.md @@ -0,0 +1,63 @@ +# Rules + +## Schema + +The syntax for rules is very basic. You just need a name, a list of terms to match that violate the rule, +and a list of alternative suggestions. + +```yaml +rules: + - name: whitelist + terms: + - whitelist + - white-list + alternatives: + - allowlist + note: An optional description why these terms are not inclusive. It can be optionally included in the output message. + # options: + # word_boundary: false + # word_boundary_start: false + # word_boundary_end: false + # include_note: false +``` + +A set of default rules is provided in [`pkg/rule/default.yaml`]({{config.repo_url}}blob/main/pkg/rule/default.yaml). + +!!! tip + If you copy these rules into your config file, be sure to put them under the `rules:` key. + +## Options + +You can configure options for each rule. Add an `options` key to your rule definition to customize. + +Current options include: + +- `word_boundary` (default: `false`) + * If `true`, terms will trigger findings when they are surrounded by ASCII word boundaries. + * If `false`, will trigger findings if the term if found anywhere in the line, regardless if it is within an ASCII word boundary. + * !!! note + setting `word_boundary` to `true` will always win out over `word_boundary_start` and `word_boundary_end` + +- `word_boundary_start` (default: `false`) + * If `true`, terms will trigger findings when they begin with an ASCII word boundaries. + * If `false`, will trigger findings if the term if found anywhere in the line, regardless if it begins with an ASCII word boundary. + +- `word_boundary_end` (default: `false`) + * If `true`, terms will trigger findings when they end with an ASCII word boundaries. + * If `false`, will trigger findings if the term if found anywhere in the line, regardless if it ends with an ASCII word boundary. + +- `include_note` (default: `not set`) + * If `true`, the rule note will be included in the output message explaining why this finding is not inclusive + * If `false`, the rule note will not be included in the output message + * If `not set`, `include_note` in your `woke` config file (ie `.woke.yml`) regulates if the note should be included in the output message (default: `false`). + +## Disabling Default Rules + +You can disable default rules by providing a rule in your `woke` config file (ie `.woke.yml`), with no terms or alternatives. + +This will disable the default `whitelist` rule: + +```yaml +rules: + - name: whitelist +``` diff --git a/docs/tools.md b/docs/tools.md new file mode 100644 index 00000000..c0828d0f --- /dev/null +++ b/docs/tools.md @@ -0,0 +1,6 @@ +# Tools + +- [GitHub Action](https://github.com/marketplace/actions/run-woke) +- [GitHub Action (reviewdog)](https://github.com/marketplace/actions/run-woke-with-reviewdog) +- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=get-woke.vscode-woke) +- [VIM Plugin](https://github.com/get-woke/vim-woke) diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 00000000..bfccdfd7 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,253 @@ +# Usage + +```text +$ woke --help + +woke is a linter that will check your source code for usage of non-inclusive +language and provide suggestions for alternatives. Rules can be customized +to suit your needs. + +Provide a list file globs for files you'd like to check. + +Usage: + woke [globs ...] [flags] + +Flags: + -c, --config string Config file (default is .woke.yaml in current directory, or $HOME) + --debug Enable debug logging + --exit-1-on-failure Exit with exit code 1 on failures + -h, --help help for woke + --no-ignore Ignored files in .gitignore, .ignore, .wokeignore, .git/info/exclude, and inline ignores are processed + -o, --output string Output type [text,simple,github-actions,json,sonarqube] (default "text") + --stdin Read from stdin + -v, --version version for woke +``` + +## Config file +Configure your custom rules config in `.woke.yaml` or `.woke.yml`. `woke` uses the following precedence order. Each item takes precedence over the item below it: + +- `current working directory` +- `$HOME` + +This file will be picked up automatically up your customizations without needing to supply it with the `-c` flag. + +See [example.yaml]({{config.repo_url}}blob/main/example.yaml) for an example of adding custom rules. +You can also supply your own rules with `-c path/to/rules.yaml` if you want to handle different rulesets. + +## Inputs + +### File globs + +By default, `woke` will run against all text files in your current directory. +To change this, supply a space-separated list of globs as the first argument. + +This can be something like `**/*.go`, or a space-separated list of filenames. + +```bash +$ woke test.txt +test.txt:2:2-11: `Blacklist` may be insensitive, use `denylist`, `blocklist` instead (warning) +* Blacklist + ^ +test.txt:3:2-12: `White-list` may be insensitive, use `allowlist` instead (warning) +* White-list + ^ +test.txt:4:2-11: `whitelist` may be insensitive, use `allowlist` instead (warning) +* whitelist + ^ +test.txt:5:2-11: `blacklist` may be insensitive, use `denylist`, `blocklist` instead (warning) +* blacklist + ^ +``` + +### STDIN + +You can also provide text to `woke` via STDIN (Standard Input) + +```bash +$ echo "This has whitelist from stdin" | woke --stdin +/dev/stdin:1:9-18: `whitelist` may be insensitive, use `allowlist` instead (warning) +This has whitelist from stdin + ^ +``` + +This option may not be used at the same time as [File Globs](#file-globs) + +## Outputs + +Options for output include text (default), simple, json, github-actions, or sonarqube format. +The following fields are supported, depending on format: + +| Field | Description | +| ------------ | ------------ | +| filepath | Relative path to file including filename | +| rulename | Name of the rule from the config file | +| termname | Specific term that was found in the text | +| alternative | List of alternative terms to use instead | +| note | Note about reasoning for inclusion | +| severity | From config, one of "error", "warning", or "info" | +| optionbool | Option value, true or false | +| linecontents | Contents of the line with finding | +| lineno | Line number, 1 based | +| startcol | Starting column number, 0 based | +| endcol | Ending column number, 0 based | +| description | Description of finding | + +Output is sent to STDOUT (Standard Output), which may be redirected to a file to save the results of a scan. + +### Text + +!!! example "" + `woke -o text` + +`text` is the default output format for woke. Displays each result on two lines. Includes color formatting if the terminal supports it. + +##### Structure + +``` +::-: () + +``` + +### Simple + +!!! example "" + `woke -o simple` + +`simple` is a format similar to text, but without color support and with each result on a single line. + +##### Structure + +``` +::: +``` + +### GitHub Actions + +!!! example "" + `woke -o github-actions` + +The `github-actions` output type is intended for integration with [GitHub Actions](https://github.com/features/actions). See [woke-action](https://github.com/get-woke/woke-action) for more information on integration. + +##### Structure + +``` +:: file=,line=,col=:: +``` + +### JSON + +!!! example "" + `woke -o json` + +Outputs the results as a series of [`json`](https://www.json.org/json-en.html) formatted structures, one per line. In order to parse as a JSON document, each line must be processed separately. This output type includes every field available in woke. + + +##### Structure +!!! info inline end + Actual output from woke will be consolidated JSON. Pretty-JSON here is just for readability. + +```json +{ + "Filename": "", + "Results": [ + { + "Rule": { + "Name": "", + "Terms": [ + "", + ... + ], + "Alternatives": [ + "", + ... + ], + "Note": "", + "Severity": "", + "Options": { + "WordBoundary": , + "WordBoundaryStart": , + "WordBoundaryEnd": , + "IncludeNote": + } + }, + "Finding": "", + "Line": "", + "StartPosition": { + "Filename": "", + "Offset": 0, + "Line": , + "Column": + }, + "EndPosition": { + "Filename": "", + "Offset": 0, + "Line": , + "Column": + }, + "Reason": "" + } + ] +} +``` + +### SonarQube + +!!! example "" + `woke -o sonarqube` + +Format used to populate results into the popular [SonarQube](https://www.sonarqube.org/) code quality tool. Note: `woke` is not executed as part of SonarQube itself, so must be run and the results file output prior to execution. Typically woke would be executed with an automation server such as Jenkins, Travis CI or Github Actions prior to creating the SonarQube report. For details on the file format, see [Generic Issue Input Format](https://docs.sonarqube.org/latest/analysis/generic-issue/). The [Analysis Parameter](https://docs.sonarqube.org/latest/analysis/analysis-parameters/) `sonar.externalIssuesReportPaths` is used to point to the path to the report file generated by `woke`. + +##### Structure + +!!! info inline end + Actual output from woke will be consolidated JSON. Pretty-JSON here is just for readability. + +```json +{ + "issues": [ + { + "engineId": "woke", + "ruleId": "", + "primaryLocation": { + "message": "", + "filePath": "", + "textRange": { + "startLine": , + "startColumn": , + "endColumn": + } + }, + "type": "CODE_SMELL", + "severity": "" + } + ] +} +``` + +!!! note + `` is mapped from severity, such that an error in `woke` is translated to a `MAJOR`, warning to a `MINOR`, and info to `INFO` + +## Exit Code + +By default, `woke` will exit with a successful exit code when there are any rule failures. +The idea is, if you run `woke` on PRs, you may not want to block a merge, but you do +want to inform the author that they can make better word choices. + +If you're using `woke` on PRs, you can choose to enforce these rules with a non-zero +exit code by running `woke --exit-1-on-failure`. + +## Parallelism + +!!! error "Advanced Configuration" + It's unlikely that you will need to adjust parallelism. But in case you do, if you are running `woke` + with limited resources, and/or against a very large directory, you may want to restrict the number of + threads that `woke` uses. + +By default, `woke` will parse files in parallel and will consume as many resources as it can, unbounded. +This means `woke` will be fast, but might run out of memory, depending on how large the files/lines are. + +We can limit these allocations by bounding the number of files read in parallel. To accomplish this, +set the environment variable `WORKER_POOL_COUNT` to an integer value of the fixed number of goroutines +you would like to spawn for reading files. + +Read more about go's concurrency patterns [here](https://blog.golang.org/pipelines). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..e9b1bc73 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,102 @@ +site_name: "Woke - Detect non-inclusive language in your source code" + +site_author: Caitlin Elfring +site_description: Detect non-inclusive language in your source code. +theme: + name: material + custom_dir: docs/overrides + logo: assets/default-monochrome.svg + favicon: assets/favicon.ico + palette: + primary: black + accent: orange + icon: + repo: fontawesome/brands/github + admonition: + note: fontawesome/solid/sticky-note + abstract: fontawesome/solid/book + info: fontawesome/solid/info-circle + tip: fontawesome/solid/bullhorn + success: fontawesome/solid/check + question: fontawesome/solid/question-circle + warning: fontawesome/solid/exclamation-triangle + failure: fontawesome/solid/bomb + danger: fontawesome/solid/skull + bug: fontawesome/solid/robot + example: fontawesome/solid/flask + quote: fontawesome/solid/quote-left + features: + - navigation.instant + - navigation.tabs + - navigation.tracking + - navigation.sections + - navigation.expand + - navigation.top + - toc.integrate +nav: + - Introduction: index.md + - Getting Started: + - Installation: installation.md + - User Guide: + - Usage: usage.md + - Rules: rules.md + - Ignoring: ignore.md + - More Info: + About: about.md + Tools: tools.md + +markdown_extensions: + - admonition + - abbr + - attr_list + - def_list + - footnotes + - meta + - md_in_html + - toc: + permalink: true + toc_depth: 4 + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji + - pymdownx.highlight + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + repo_url_shorthand: true + user: squidfunk + repo: mkdocs-material + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences + - pymdownx.tabbed + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + +plugins: + - macros + +repo_url: https://github.com/get-woke/woke +repo_name: get-woke/woke +edit_uri: edit/main/docs/ + +copyright: Copyright © 2020 - 2021 Caitlin Elfring + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/get-woke + name: GitHub + - icon: fontawesome/brands/docker + link: https://hub.docker.com/r/getwoke/woke/ + name: Docker + # TODO + # analytics: + # provider: google + # property: G-XXXXXXXXXX + # property: UA-XXXXXXXX-X From 46c03c2048eaebfaea34d300775dcf220a91e817 Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Wed, 11 Aug 2021 22:30:42 -0400 Subject: [PATCH 02/15] Commit as github-actions bot --- .github/workflows/docs.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 55658d13..8300ad5b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -17,4 +17,8 @@ jobs: with: python-version: 3.x - run: pip install -r docs/requirements.txt - - run: mkdocs gh-deploy --force + - run: | + # Hard-code user configuration + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git config user.name "github-actions" + mkdocs gh-deploy --force From eca00307805eecdf067787985eca3f7ed7b8a2d4 Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Wed, 11 Aug 2021 22:35:53 -0400 Subject: [PATCH 03/15] Fix license link --- docs/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/about.md b/docs/about.md index 10760aa5..4e6d23f7 100644 --- a/docs/about.md +++ b/docs/about.md @@ -42,4 +42,4 @@ The following projects provided inspiration for parts of `woke` ## License This application is licensed under the MIT License, you may obtain a copy of it -[here](LICENSE). +[here]({{config.repo_url}}blob/main/LICENSE). From 3efee8564e8e8df957e9ca057097a06ebe1691b5 Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Wed, 11 Aug 2021 22:55:16 -0400 Subject: [PATCH 04/15] Configure custom accent theme --- docs/css/extra.css | 3 +++ mkdocs.yml | 4 +++- 2 files changed, 6 insertions(+), 1 deletion(-) create mode 100644 docs/css/extra.css diff --git a/docs/css/extra.css b/docs/css/extra.css new file mode 100644 index 00000000..041392df --- /dev/null +++ b/docs/css/extra.css @@ -0,0 +1,3 @@ +[data-md-color-scheme="woke"] { + --md-accent-fg-color: #D1A103; +} diff --git a/mkdocs.yml b/mkdocs.yml index e9b1bc73..1c0ad623 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,8 +8,8 @@ theme: logo: assets/default-monochrome.svg favicon: assets/favicon.ico palette: + scheme: woke primary: black - accent: orange icon: repo: fontawesome/brands/github admonition: @@ -87,6 +87,8 @@ edit_uri: edit/main/docs/ copyright: Copyright © 2020 - 2021 Caitlin Elfring +extra_css: + - css/extra.css extra: social: - icon: fontawesome/brands/github From cb5233ebe8849d510b60856d3496e50dc37b3d5b Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Thu, 12 Aug 2021 07:12:41 -0400 Subject: [PATCH 05/15] Search --- mkdocs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index 1c0ad623..6ffa189d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,6 +33,8 @@ theme: - navigation.expand - navigation.top - toc.integrate + - search.suggest + - search.highlight nav: - Introduction: index.md - Getting Started: @@ -80,6 +82,7 @@ markdown_extensions: plugins: - macros + - search repo_url: https://github.com/get-woke/woke repo_name: get-woke/woke From 2abfca40fb52adced8f99fa0525262e60dae5cfa Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Thu, 12 Aug 2021 07:36:09 -0400 Subject: [PATCH 06/15] Update docs readme --- docs/README.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 0ecf0d66..cd0e449e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,20 @@ # Woke documentation site -TODO +Woke uses the [material](https://squidfunk.github.io/mkdocs-material/) MkDocs theme. + +You can find the live site at . + +See [mkdocs.yml](../mkdocs.yml) for details. + +## Running locally + +```bash +docker build -t woke-mkdocs -f docs/Dockerfile . +docker run --rm -v `pwd`:/workdir -w /workdir -p 8000:8000 woke-mkdocs +``` + +You can now access the site locally via `http://localhost:8000`. Auto-reload is enabled + +## Deploying + +Any changes made to the `docs` directory will be automatically deployed on merges to `main`. From 76ceae55ead86a979470543bdbda41b9cb1761e6 Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Thu, 12 Aug 2021 07:43:10 -0400 Subject: [PATCH 07/15] Update rule options docs --- docs/rules.md | 48 ++++++++++++++++++++++++++++++------------------ mkdocs.yml | 4 +++- 2 files changed, 33 insertions(+), 19 deletions(-) diff --git a/docs/rules.md b/docs/rules.md index ae393237..3cd97584 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -32,24 +32,36 @@ You can configure options for each rule. Add an `options` key to your rule defin Current options include: -- `word_boundary` (default: `false`) - * If `true`, terms will trigger findings when they are surrounded by ASCII word boundaries. - * If `false`, will trigger findings if the term if found anywhere in the line, regardless if it is within an ASCII word boundary. - * !!! note - setting `word_boundary` to `true` will always win out over `word_boundary_start` and `word_boundary_end` - -- `word_boundary_start` (default: `false`) - * If `true`, terms will trigger findings when they begin with an ASCII word boundaries. - * If `false`, will trigger findings if the term if found anywhere in the line, regardless if it begins with an ASCII word boundary. - -- `word_boundary_end` (default: `false`) - * If `true`, terms will trigger findings when they end with an ASCII word boundaries. - * If `false`, will trigger findings if the term if found anywhere in the line, regardless if it ends with an ASCII word boundary. - -- `include_note` (default: `not set`) - * If `true`, the rule note will be included in the output message explaining why this finding is not inclusive - * If `false`, the rule note will not be included in the output message - * If `not set`, `include_note` in your `woke` config file (ie `.woke.yml`) regulates if the note should be included in the output message (default: `false`). +### `word_boundary` + +:octicons-milestone-24: Default: `false` + +* If `true`, terms will trigger findings when they are surrounded by ASCII word boundaries. +* If `false`, will trigger findings if the term if found anywhere in the line, regardless if it is within an ASCII word boundary. +* !!! note + setting `word_boundary` to `true` will always win out over `word_boundary_start` and `word_boundary_end` + +### `word_boundary_start` + +:octicons-milestone-24: Default: `false` + +* If `true`, terms will trigger findings when they begin with an ASCII word boundaries. +* If `false`, will trigger findings if the term if found anywhere in the line, regardless if it begins with an ASCII word boundary. + +### `word_boundary_end` + +:octicons-milestone-24: Default: `false` + +* If `true`, terms will trigger findings when they end with an ASCII word boundaries. +* If `false`, will trigger findings if the term if found anywhere in the line, regardless if it ends with an ASCII word boundary. + +### `include_note` + +:octicons-milestone-24: Default: `not set` + +* If `true`, the rule note will be included in the output message explaining why this finding is not inclusive +* If `false`, the rule note will not be included in the output message +* If `not set`, `include_note` in your `woke` config file (ie `.woke.yml`) regulates if the note should be included in the output message (default: `false`). ## Disabling Default Rules diff --git a/mkdocs.yml b/mkdocs.yml index 6ffa189d..0fae2a11 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -64,7 +64,9 @@ markdown_extensions: smart_enable: all - pymdownx.caret - pymdownx.details - - pymdownx.emoji + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg - pymdownx.highlight - pymdownx.inlinehilite - pymdownx.keys From fc095b2f81cf13cfb59d940c0fc939624efd3bc8 Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Thu, 12 Aug 2021 07:47:15 -0400 Subject: [PATCH 08/15] Run some PR checks --- .github/workflows/docs.yml | 28 +++++++++++++++++++++++++--- .gitignore | 3 +++ 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8300ad5b..886bca52 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,4 +1,4 @@ -name: Update mkdocs page +name: MkDocs page on: push: @@ -8,8 +8,14 @@ on: - "docs/**" - mkdocs.yml - .github/workflows/docs.yml + pull_request: + paths: + - "docs/**" + - mkdocs.yml + - .github/workflows/docs.yml + jobs: - deploy: + mkdocs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 @@ -17,8 +23,24 @@ jobs: with: python-version: 3.x - run: pip install -r docs/requirements.txt - - run: | + + - name: MkDocs build + if: github.event_name == 'pull_request' + run: mkdocs build + + - name: MkDocs deploy + if: github.event_name != 'pull_request' + run: | # Hard-code user configuration git config user.email "41898282+github-actions[bot]@users.noreply.github.com" git config user.name "github-actions" mkdocs gh-deploy --force + markdownlint: + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' + steps: + - uses: actions/checkout@v2 + - name: MarkdownLint + uses: actionshub/markdownlint@2.0.2 + with: + path: docs diff --git a/.gitignore b/.gitignore index e755a6bf..ece01973 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,6 @@ dist/* # pprof files *.test *.prof + +# mkdocs +site/ From bbe2a08beb9617fc1d32303f49881bea517e8944 Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Thu, 12 Aug 2021 07:47:26 -0400 Subject: [PATCH 09/15] Add dockerfile --- docs/Dockerfile | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/Dockerfile diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 00000000..c2bb2a22 --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,9 @@ +FROM python:3-alpine + +WORKDIR /workdir +COPY docs/requirements.txt /workdir +RUN pip install -r /workdir/requirements.txt + +EXPOSE 8000 + +CMD ["mkdocs", "serve", "--dev-addr", "0.0.0.0:8000"] From 01e40cf6b2c4283afeabd95f7253e4b997e9dea0 Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Thu, 12 Aug 2021 07:50:57 -0400 Subject: [PATCH 10/15] Remove custom admonition, insiders only --- docs/rules.md | 5 +---- mkdocs.yml | 13 ------------- 2 files changed, 1 insertion(+), 17 deletions(-) diff --git a/docs/rules.md b/docs/rules.md index 3cd97584..70aca199 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -30,16 +30,13 @@ A set of default rules is provided in [`pkg/rule/default.yaml`]({{config.repo_ur You can configure options for each rule. Add an `options` key to your rule definition to customize. -Current options include: - ### `word_boundary` :octicons-milestone-24: Default: `false` * If `true`, terms will trigger findings when they are surrounded by ASCII word boundaries. * If `false`, will trigger findings if the term if found anywhere in the line, regardless if it is within an ASCII word boundary. -* !!! note - setting `word_boundary` to `true` will always win out over `word_boundary_start` and `word_boundary_end` +* !!! warning "setting `word_boundary` to `true` will always win out over `word_boundary_start` and `word_boundary_end`" ### `word_boundary_start` diff --git a/mkdocs.yml b/mkdocs.yml index 0fae2a11..0e415fe2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,19 +12,6 @@ theme: primary: black icon: repo: fontawesome/brands/github - admonition: - note: fontawesome/solid/sticky-note - abstract: fontawesome/solid/book - info: fontawesome/solid/info-circle - tip: fontawesome/solid/bullhorn - success: fontawesome/solid/check - question: fontawesome/solid/question-circle - warning: fontawesome/solid/exclamation-triangle - failure: fontawesome/solid/bomb - danger: fontawesome/solid/skull - bug: fontawesome/solid/robot - example: fontawesome/solid/flask - quote: fontawesome/solid/quote-left features: - navigation.instant - navigation.tabs From 81ba01574eec643e6729a278db37db64499bf80c Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Thu, 12 Aug 2021 07:55:00 -0400 Subject: [PATCH 11/15] wokeignore docs markdown files --- .wokeignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.wokeignore b/.wokeignore index 102aba62..60a67cc9 100644 --- a/.wokeignore +++ b/.wokeignore @@ -3,3 +3,4 @@ pkg/rule/default.yaml example.yaml README.md testdata +docs/*.md From 867031727c06a1e6b36bb469fbbe58fa4ecd06e6 Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Thu, 12 Aug 2021 07:56:21 -0400 Subject: [PATCH 12/15] Update pre-commit doc for installation link --- scripts/pre-commit.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/pre-commit.sh b/scripts/pre-commit.sh index a9098549..8ba9e546 100755 --- a/scripts/pre-commit.sh +++ b/scripts/pre-commit.sh @@ -3,7 +3,7 @@ set -e if ! type woke > /dev/null; then - echo "woke is not installed, or is not available in your PATH. See https://github.com/get-woke/woke#installation." + echo "woke is not installed, or is not available in your PATH. See https://docs.getwoke.tech/installation." exit 1 fi From 3b80a4cc02463d4945408e70a8c90cd70860a92a Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Thu, 12 Aug 2021 08:02:45 -0400 Subject: [PATCH 13/15] Different markdownlint action --- .github/workflows/docs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 886bca52..652c378f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -40,7 +40,7 @@ jobs: if: github.event_name == 'pull_request' steps: - uses: actions/checkout@v2 - - name: MarkdownLint - uses: actionshub/markdownlint@2.0.2 + - uses: nosborn/github-action-markdown-cli@v2.0.0 with: - path: docs + files: docs/*.md + config_file: .markdownlint.json From d7092fe08645a594ae906b73ae89ed002377bfbd Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Thu, 12 Aug 2021 08:08:49 -0400 Subject: [PATCH 14/15] Fix markdownlint errors --- .markdownlint.json | 3 ++- docs/ignore.md | 1 - docs/usage.md | 17 +++++++++-------- mkdocs.yml | 2 +- 4 files changed, 12 insertions(+), 11 deletions(-) diff --git a/.markdownlint.json b/.markdownlint.json index bb096f00..b219f10a 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -2,5 +2,6 @@ "line-length": false, "no-emphasis-as-heading": false, "no-inline-html": false, - "first-line-h1": false + "first-line-h1": false, + "no-duplicate-header": false } diff --git a/docs/ignore.md b/docs/ignore.md index 41748a7d..8cd66056 100644 --- a/docs/ignore.md +++ b/docs/ignore.md @@ -4,7 +4,6 @@ You can ignore files by adding to your config file. All ways of ignoring files below should follow the [gitignore](https://git-scm.com/docs/gitignore) convention. - ```yaml ignore_files: - other/files/in/repo diff --git a/docs/usage.md b/docs/usage.md index bfccdfd7..7a0824bd 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -24,6 +24,7 @@ Flags: ``` ## Config file + Configure your custom rules config in `.woke.yaml` or `.woke.yml`. `woke` uses the following precedence order. Each item takes precedence over the item below it: - `current working directory` @@ -101,9 +102,9 @@ Output is sent to STDOUT (Standard Output), which may be redirected to a file to `text` is the default output format for woke. Displays each result on two lines. Includes color formatting if the terminal supports it. -##### Structure +#### Structure -``` +```text ::-: () ``` @@ -115,9 +116,9 @@ Output is sent to STDOUT (Standard Output), which may be redirected to a file to `simple` is a format similar to text, but without color support and with each result on a single line. -##### Structure +#### Structure -``` +```text ::: ``` @@ -128,9 +129,9 @@ Output is sent to STDOUT (Standard Output), which may be redirected to a file to The `github-actions` output type is intended for integration with [GitHub Actions](https://github.com/features/actions). See [woke-action](https://github.com/get-woke/woke-action) for more information on integration. -##### Structure +#### Structure -``` +```text :: file=,line=,col=:: ``` @@ -141,8 +142,8 @@ The `github-actions` output type is intended for integration with [GitHub Action Outputs the results as a series of [`json`](https://www.json.org/json-en.html) formatted structures, one per line. In order to parse as a JSON document, each line must be processed separately. This output type includes every field available in woke. +#### Structure -##### Structure !!! info inline end Actual output from woke will be consolidated JSON. Pretty-JSON here is just for readability. @@ -197,7 +198,7 @@ Outputs the results as a series of [`json`](https://www.json.org/json-en.html) f Format used to populate results into the popular [SonarQube](https://www.sonarqube.org/) code quality tool. Note: `woke` is not executed as part of SonarQube itself, so must be run and the results file output prior to execution. Typically woke would be executed with an automation server such as Jenkins, Travis CI or Github Actions prior to creating the SonarQube report. For details on the file format, see [Generic Issue Input Format](https://docs.sonarqube.org/latest/analysis/generic-issue/). The [Analysis Parameter](https://docs.sonarqube.org/latest/analysis/analysis-parameters/) `sonar.externalIssuesReportPaths` is used to point to the path to the report file generated by `woke`. -##### Structure +#### Structure !!! info inline end Actual output from woke will be consolidated JSON. Pretty-JSON here is just for readability. diff --git a/mkdocs.yml b/mkdocs.yml index 0e415fe2..872c41f8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,7 +44,7 @@ markdown_extensions: - md_in_html - toc: permalink: true - toc_depth: 4 + toc_depth: 3 - pymdownx.arithmatex: generic: true - pymdownx.betterem: From 1b213e69456e309998495bc213116fc65d327942 Mon Sep 17 00:00:00 2001 From: Caitlin Elfring Date: Thu, 12 Aug 2021 08:10:35 -0400 Subject: [PATCH 15/15] Only deploy docs on pushes to main --- .github/workflows/docs.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 652c378f..869160db 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,8 +2,7 @@ name: MkDocs page on: push: - # branches: [ main ] - branches: [ docs ] + branches: [ main ] paths: - "docs/**" - mkdocs.yml