mut
https://github.com/mongodb/mut Copyright 2023 MongoDB Inc.
mut
provides a handful of tools used in MongoDB's documentation platform.
mut-index
turns snooty-parser-generated abstract syntax trees into manifestsmut-redirects
generates redirects from our bespoke redirect definition format,mut-images
bakes SVG files into minimized SVGs with no external font requirements.mut-stage
uploads files to S3 with minimal fuss for the usermut
is licensed under the Apache License, Version 2.0.
See the LICENSE
file for details.
mut v0.9.x
exists to support the needs of MongoDB docs properties building with the legacy (giza)
toolchain. To use mut
, you need python3, along with a bunch of other dependencies.
To install mut
for use with giza, follow the instructions on the writer setup wiki.
mut
(v0.10 and later)To use mut locally, you need python 3.8 or later.
As of v0.10, each mut
release builds with poetry
.
If you do not have poetry
installed, install it following
their excellent instructions.
You should probably also python3 -m pip install wheel
if you haven't.
git checkout <tag>
poetry build
.[!NOTE] You may need to add read priveleges to your Users/<your-username>/.pyenv/ folder.
poetry install # to make sure everything's set up
poetry build # to actually build it
pip
to install the newly-generated mut
wheel:python3 -m pip install dist/whatever.whl
Alternatively, from v0.10.3, we offer a pre-built mut
bundle that includes
all the things so you need simply unzip the bundle and run the executable.
At present it only does this for Linux, though we'll probably change that at some point.
mut
To develop mut
locally, ensure you have poetry
installed by running which poetry
.
If you do not have poetry
installed, install it following
their excellent instructions.
Set up the project's dependencies.
poetry install
Make your changes to the source code.
Active a shell where the mut
commands you just built are available:
poetry shell
When you're done terminate your shell by running:
exit
To access commands, ensure the shell is running. To activate it, run the following
poetry shell
To check that tests still pass after your changes to the source code, run the following command.
make lint test
To fix your formatting run
make format
mut
From the releases page, click "Draft a new release". Create a new tag in the tag dropdown, fill out the release name and description, generate the changelog using the handy changelog generation button, and click "Publish release".
Creating the tag will run the release workflow, building the stuff and (potentially ?) creating an extra draft release which you can then delete.
Finally, update the version number in pyproject.toml.
If you're the sort of person who likes making your tags manually (like Allison):
First, update the version number in pyproject.toml and push the change to main.
Create a tag and push it to main:
git tag v0.10.3
git push origin main --tags
Creating the tag will run the release workflow, building the stuff and creating a draft release on the releases page.
Go to the releases page, find the newly-created release draft and fill out the release description, generate release notes, etc.