https://github.com/mongodb/mut Copyright 2023 MongoDB Inc.
mut provides a handful of tools used in MongoDB's documentation platform.
mut-indexturns snooty-parser-generated abstract syntax trees into manifests that can be ingested into Atlas Search to power the docs' search.mut-redirectsgenerates 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 linksmut-imagesturns SVGs into PNGs I think?mut-stageuploads 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.
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.
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)[https://python-poetry.org/docs/].
You should probably also python3 -m pip install wheel if you haven't.
- Check out the relevant tag (in this case
v0.10.2):
git checkout v0.10.2- Build a wheel using
poetry build.
poetry install # to make sure everything's set up
poetry build # to actually build it- Use
pipto install the newly-generatedmutwheel:
python3 -m pip install dist/whatever.whlAlternatively, 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.
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)[https://python-poetry.org/docs/].
-
Set up the project's dependencies.
poetry install -
Make your changes to the source code.
-
Run
make testandmake formatto check that the tests pass and fix your formatting. -
Active a shell where the
mutcommands you just built are available:poetry shell -
When you're done testing, terminate your shell by running:
exit
From the (releases page)[https://github.com/mongodb/mut/releases], 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)[https://github.com/mongodb/mut/blob/master/.github/workflows/release.yml], 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):
-
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)[https://github.com/mongodb/mut/blob/master/.github/workflows/release.yml], building the stuff and creating a draft release on the (releases page)[https://github.com/mongodb/mut/releases].
-
Go to the releases page, find the newly-created release draft and fill out the release description, generate release notes, etc.
-
Finally, update the version number in pyproject.toml.