Skip to content

npentrel/vale-mongodb

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

51 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

NOTE: This project is neither officially maintained nor endorsed by MongoDB.

This repository contains a Vale-compatible implementation of the MongoDB Documentation Style Guide.

The goal of this project is to provide a helpful style guide adherance checker.

Build Status Vale version license

Getting Started

The following will install vale globally. If you would like to configure each repo individually scroll down to the Per Repo installation. You only need to complete either the Global or the Per Repo Installation.

Global Installation [Recommended]

❗ MongoDB requires Vale >= 1.0.0. ❗

  1. Install vale. If you do not have brew installed follow these installation instructions.

    brew install vale
  2. In the folder where you keep code, clone this repo:

    git clone git@github.com:10gen/mongodb-vale.git
  3. Run the following and copy the output.

    cd mongodb-vale
    pwd
  4. Depending on your chosen shell, open up your ~/.bashrc or ~/.zshrc file and append the following lines swapping out VALEDIR for the output you received in the previous step:

    export PATH=$PATH:VALEDIR/bin
    alias vale="vale --config VALEDIR/.vale.ini"
    # Example of both
    # export PATH=$PATH:/Users/naomi/coding/vale-mongodb/bin
    # alias vale="vale --config /Users/naomi/coding/vale-mongodb/.vale.ini"
  5. In the monodb-vale folder open up the vale-check script inside the bin folder and replace VALEDIR with the output you received in step 3.

    Example file:

    #! /bin/bash
    
    vale --config /Users/naomi/coding/vale-mongodb/.vale.ini $(git diff --diff-filter=d --name-only $1)
    whitespace-check $(git diff --diff-filter=d --name-only $1)
  6. Run source ~/.bashrc or source ~/.zshrc. Or restart your terminal.

  7. Install rst2html. This allows vale to interpret rst files.

    You can check if you already have rst2html installed by running which rst2html into your terminal. If you don't have rst2html installed run pip3 install rst2html or pip install rst2html.

    Try running which rst2html again. If you do not get a path to the command as the output, try running which rst2thml.py. If the second command worked, create a symlink for rst2html.py:

    sudo ln -s rst2html.py /usr/local/bin/rst2html
    # you need to enter your password to confirm this

    Again try running which rst2html. If it doesn't work (or if which rst2html.py also didn't work for you), you need to add the folder that contains rst2html to your PATH. Open up either your ~/.bashrc or ~/.zshrc file (depending on what you use) and add the following lines at the bottom of the file, swapping out the /usr/local/bin/ with the path to your rst2html file:

    # Append path to rst2html for vale
    export PATH=$PATH:/usr/local/bin/

    Do not proceed until you your terminal returns a path to the installed rst2html script when you run which rst2html. Installing this ensures things like codeblocks aren't checked against the style guide (- unfortunately this doesn't work for all codeblocks - any Sphinx-modifiers like :copyable: mean the codeblocks are not ignored - if this bothers you we'll need to see if we can get budget to pay for vale-server which would allow us to integrate with Sphinx).

  8. To run vale against a file use:

    vale /path/to/file

    Inside the mongodb-vale repo, you can run vale test.rst to run vale on an example file. The output should end with the following line:

    ✖ 1 error, 1 warning and 1 suggestion in 1 file.
  9. If you want to run vale against all files that have changed since a given commit hash use the vale-check wrapper:

    vale-check <HASH>
    # example: vale-check
    # example: vale-check HEAD
    # example: vale-check HEAD~3
    # example: vale-check abc123

    This will also run a whitespace check on the files.

    Inside the mongodb-vale repo, you can run vale-check 36b93db2 to run vale on an example file. You should see the same output as in step 6 with an additiona note that You missed a new line after a directive..

Per Repo Installation

❗ MongoDB requires Vale >= 1.0.0. ❗

  1. Install vale. If you do not have brew installed follow these installation instructions.

    brew install vale
  2. In the folder where you keep code, clone this repo:

    git clone git@github.com:10gen/mongodb-vale.git
  3. Inside a folder that contains docs, create a symbolic link to the vale folder, the .vale.ini file and to the vale-check and whitespace-check script:

    ln -s $(pwd)/vale /path/to/docs/folder/
    ln -s $(pwd)/.vale.ini /path/to/docs/folder/
    ln -s $(pwd)/vale-check /path/to/docs/folder/
    ln -s $(pwd)/whitespace-check /path/to/docs/folder/
    # example: ln -s $(pwd)/vale /Users/naomi/coding/docs/
    # example: ln -s $(pwd)/.vale.ini /Users/naomi/coding/docs/
    # example: ln -s $(pwd)/vale-check /Users/naomi/coding/docs/
    # example: ln -s $(pwd)/whitespace-check /Users/naomi/coding/docs/
  4. To ensure these symlinks do not accidentally get added to git run:

    #!/bin/sh
    GITIGNOREFILE=$(git config --get core.excludesfile)
    if [ -z "$GITIGNOREFILE" ]
    then
          GITIGNOREFILE=~/.gitignore_global
          git config --global core.excludesfile '~/.gitignore_global'
          echo "Created ~/.gitignore_global"
    else
          echo "Appending to existing global gitignore file"
    fi
    GITIGNOREFILE="${GITIGNOREFILE/#\~/$HOME}"
    echo "
    vale
    .vale.ini
    vale-check
    whitespace-check" >> $GITIGNOREFILE

    This script checks if you already have a global git ignore file and sets one up if you don't. It then adds the files we created symlinks for to your global gitignore file.

  5. Install rst2html. This allows vale to interpret rst files.

    You can check if you already have rst2html installed by running which rst2html into your terminal. If you don't have rst2html installed run pip3 install rst2html or pip install rst2html.

    Try running which rst2html again. If you do not get a path to the command as the output, try running which rst2thml.py. If the second command worked, create a symlink for rst2html.py:

    sudo ln -s rst2html.py /usr/local/bin/rst2html
    # you need to enter your password to confirm this

    Again try running which rst2html. If it doesn't work (or if which rst2html.py also didn't work for you), you need to add the folder that contains rst2html to your PATH. Open up either your ~/.bashrc or ~/.zshrc file (depending on what you use) and add the following lines at the bottom of the file, swapping out the /usr/local/bin/ with the path to your rst2html file:

    # Append path to rst2html for vale
    export PATH=$PATH:/usr/local/bin/

    Do not proceed until you your terminal returns a path to the installed rst2html script when you run which rst2html. Installing this ensures things like codeblocks aren't checked against the style guide (- unfortunately this doesn't work for all codeblocks - any Sphinx-modifiers like :copyable: mean the codeblocks are not ignored - if this bothers you we'll need to see if we can get budget to pay for vale-server which would allow us to integrate with Sphinx).

  6. To run vale against a file use:

    vale /path/to/file

    Inside the mongodb-vale repo, you can run vale test.rst to run vale on an example file. The output should end with the following line:

    ✖ 1 error, 1 warning and 1 suggestion in 1 file.
  7. If you want to run vale against all files that have changed since a given commit hash use the vale-check wrapper:

    ./vale-check <HASH>
    # example: ./vale-check
    # example: ./vale-check HEAD
    # example: ./vale-check HEAD~3
    # example: ./vale-check abc123

    This will also run a whitespace check on the files.

    Inside the mongodb-vale repo, you can run ./vale-check 36b93db2 to run vale on an example file. You should see the same output as in step 6 with an additiona note that You missed a new line after a directive..

Usage

To learn how to use Vale, see Usage.

Turning Rules Off

To turn off a given rule open the .vale.ini file and set the respective variable to NO. Example:

MongoDB.Abbreviations = NO

Using Vale in VSCode

NOTE: Please follow the steps in Getting Started first!

  1. Install the vale extension
  2. Navigate to the vale extension settings:
    • Turn on Use CLI
    • Set Lint Context to a reasonable number like 30
    • Specify the absolute path to the .vale.ini file for Vale CLI: Config. The file is in the repo you cloned in Getting Started.
    • Set the min alert level to suggestion - a lot of the rules are coded as suggestions.
    • Specify the path to your vale installation. To find this path run which vale in your terminal and copy the path. This path can't include any spaces before or after the path.

If you cannot use the VSCode UI to configure vale you will need to add these settings to your settings.json:

    "vale.server.lintContext": 40,
    "vale.valeCLI.config": "/path/to/your/.vale.ini",
    "vale.valeCLI.minAlertLevel": "suggestion",
    "vale.valeCLI.path": "/usr/local/bin/vale",

Using Vale-Server

After the 30 day trial period, a license for Vale server can be obtained here. Vale server allows you to also make use of LanguageTool's open-source grammar checker.

To install Vale Server, follow these instructions and use the .vale.ini file from the repo you cloned. Swap out the path to the styles (StylesPath = vale/styles) in line 4 with the absolute path to the file (in my case StylesPath = /Users/naomi/coding/vale-mongodb/vale/styles).

You can install LanguageTool for macOS. Follow the instructions to integrate LanguageTool with Vale-Server.

If you set up Vale for VS-Code you can point it to your vale-server installation to make use of the extra features (via the extension settings).

Using LanguageTool

While not documented it is possible to use the LanguageTool extension with the Vale CLI version. If you want to do this add LanguageTool to your styles and a ProcessTimeout - both inside yor .vale.ini file.

ProcessTimeout = 5

# Specify how to test a particular type of files
[*.{rst,txt}]
BasedOnStyles = MongoDB, write-good, vale, proselint, LanguageTool

You will need to run LanguageTool on port 8081. If you have followed the instructions to install Vale Server you can change the code there and click Apply & Restart. If you are encountering issues try running vale on the commandline.

Repository Structure

/vale/styles/MongoDB
The YAML-based rule implementations that make up our style.
/.vale.ini
The vale configuration file.
/vale-check
A wrapper script that allows you to run vale and a whitespace-check agains recently changed files in git.
/whitespace-check
A script that checks for whitespace issues.

Credits

Some rules, especially regexes, are based on other project's rules. Where I didn't leave rules in a folder with the name of the creator, I have pointed out in the individual files where the rules/regexes stem from.

Most commonly reused rules are from:

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages