mongodb / mut

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 manifests that can be ingested into Atlas Search to power the docs' search.
• mut-redirects generates redirects from our bespoke redirect definition format, making it "easy" to ensure that readers never find themselves on a 404ing page when swapping versions or following old links
• mut-images turns SVGs into PNGs I think?
• mut-stage uploads files to S3 with minimal fuss for the user

mut is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Installation

Legacy mut (v0.9 and earlier)

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.

Modern 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.

1. Check out the tag you want to build:

git checkout <tag>

2. Build a wheel using 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

3. Use 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.

Developing 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.

1. Set up the project's dependencies.

   poetry install
   

2. Make your changes to the source code.

3. Run make test and make format to check that the tests pass and fix your formatting.

4. Active a shell where the mut commands you just built are available:

   poetry shell
   

5. When you're done testing, terminate your shell by running:

   exit
   

Releasing mut

Do it the easy way

From the releases page, click "Draft a new release". Create a new tag in the tag dropdown, fill ou 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.

Generate the tag manually because you like commandline git

If you're the sort of person who likes making your tags manually (like Allison):

1. First, update the version number in pyproject.toml.

2. Create a tag and push it to master:

   git tag v0.10.3
   git push origin master --tags

   Creating the tag will run the release workflow, building the stuff and creating a draft release on the releases page.

3. Go to the releases page, find the newly-created release draft and fill out the release description, generate release notes, etc.

mut's Issues

Unprivileged installation package/instructions

Please publish mut to pypi or provide instructions for installing it in an unprivileged environment.

tk% bash -c "$(curl -fsSL https://raw.githubusercontent.com/mongodb/mut/master/install.sh)"
Install dependencies:  sudo apt-get update
OK? n

We trust you have received the usual lecture from the local System
Administrator. It usually boils down to these three things:

    #1) Respect the privacy of others.
    #2) Think before you type.
    #3) With great power comes great responsibility.

[sudo] password for mpush: 
Sorry, try again.
[sudo] password for mpush: 
Sorry, try again.
[sudo] password for mpush: 
sudo: 3 incorrect password attempts

Even though I declined to have mut installer make changes to my system, it attempted to do so anyway and failed.