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.
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.
❗ MongoDB requires Vale >= 1.0.0. ❗
-
Install
vale
. If you do not havebrew
installed follow these installation instructions.brew install vale
-
In the folder where you keep code, clone this repo:
git clone git@github.com:10gen/mongodb-vale.git
-
Run the following and copy the output.
cd mongodb-vale pwd
-
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"
-
In the
monodb-vale
folder open up thevale-check
script inside thebin
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)
-
Run
source ~/.bashrc
orsource ~/.zshrc
. Or restart your terminal. -
Install
rst2html
. This allows vale to interpretrst
files.You can check if you already have
rst2html
installed by runningwhich rst2html
into your terminal. If you don't have rst2html installed runpip3 install rst2html
orpip install rst2html
.Try running
which rst2html
again. If you do not get a path to the command as the output, try runningwhich rst2thml.py
. If the second command worked, create a symlink forrst2html.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 ifwhich rst2html.py
also didn't work for you), you need to add the folder that containsrst2html
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 yourrst2html
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 forvale-server
which would allow us to integrate with Sphinx). -
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.
-
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 thatYou missed a new line after a directive.
.
❗ MongoDB requires Vale >= 1.0.0. ❗
-
Install
vale
. If you do not havebrew
installed follow these installation instructions.brew install vale
-
In the folder where you keep code, clone this repo:
git clone git@github.com:10gen/mongodb-vale.git
-
Inside a folder that contains docs, create a symbolic link to the
vale
folder, the.vale.ini
file and to thevale-check
andwhitespace-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/
-
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.
-
Install
rst2html
. This allows vale to interpretrst
files.You can check if you already have
rst2html
installed by runningwhich rst2html
into your terminal. If you don't have rst2html installed runpip3 install rst2html
orpip install rst2html
.Try running
which rst2html
again. If you do not get a path to the command as the output, try runningwhich rst2thml.py
. If the second command worked, create a symlink forrst2html.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 ifwhich rst2html.py
also didn't work for you), you need to add the folder that containsrst2html
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 yourrst2html
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 forvale-server
which would allow us to integrate with Sphinx). -
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.
-
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 thatYou missed a new line after a directive.
.
To learn how to use Vale, see Usage.
To turn off a given rule open the .vale.ini
file and set the respective variable to NO
. Example:
MongoDB.Abbreviations = NO
NOTE: Please follow the steps in Getting Started first!
- Install the vale extension
- Navigate to the vale extension settings:
- Turn on
Use CLI
- Set
Lint Context
to a reasonable number like30
- Specify the absolute path to the
.vale.ini
file forVale CLI: Config
. The file is in the repo you cloned inGetting 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.
- Turn on
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",
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).
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.
/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.
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: