slashml · pr-test1 · Sep 18, 2025 · Sep 18, 2025 · Sep 18, 2025 · Sep 18, 2025
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -9,20 +9,24 @@ description: How to contribute to Magemaker
 We love your input! We want to make contributing to Magemaker as easy and transparent as possible, whether it's:
 
 - Reporting a bug
-- Discussing the current state of the code
+- Discussing the current state of the code or docs
 - Submitting a fix
 - Proposing new features
 - Becoming a maintainer
 
+<Note>
+  If you add a user-facing feature (e.g. a new CLI flag, REST route, or YAML option) **you must also update the documentation**. See “Documentation Changes” below.
+</Note>
+
 ## Ways to Contribute
 
 ### 1. Report Issues
 
 If you encounter any bugs or have feature requests:
 
 1. Go to our GitHub repository
-2. Click on "Issues"
-3. Click "New Issue"
+2. Click on **Issues**
+3. Click **New Issue**
 4. Choose the appropriate template (Bug Report or Feature Request)
 5. Fill out the template with as much detail as possible
 
@@ -33,10 +37,10 @@ If you encounter any bugs or have feature requests:
 ### 2. Submit Pull Requests
 
 1. Fork the repo and create your branch from `main`
-2. If you've added code that should be tested, add tests
-3. If you've changed APIs, update the documentation
-4. Ensure the test suite passes
-5. Make sure your code lints
+2. If you've added code that should be tested, add tests (`pytest`)
+3. If you've changed APIs, update or create a docs page (see **Documentation Changes**)
+4. Ensure the test suite passes: `pytest -q`
+5. Run linters/formatters (`black . && isort . && flake8`)
 6. Issue that pull request!
 
 <Card title="Creating a pull request" icon="github" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request">
@@ -45,24 +49,84 @@ If you encounter any bugs or have feature requests:
 
 ## Development Process
 
-1. Fork the repo
-2. Create a new branch: `git checkout -b my-feature-branch`
-3. Make your changes
-4. Push to your fork and submit a pull request
-5. Wait for a review and address any comments
-
-## Pull Request Guidelines
-
-- <Icon icon="check" iconType="solid" /> Update documentation as needed
-- <Icon icon="check" iconType="solid" /> Add tests if applicable
-- <Icon icon="check" iconType="solid" /> Follow the existing code style
-- <Icon icon="check" iconType="solid" /> Keep PRs small and focused
-- <Icon icon="check" iconType="solid" /> Write clear commit messages
+<Steps>
+  <Step title="Fork & Clone">
+    ```bash
+    git clone https://github.com/YOUR_USERNAME/magemaker.git
+    cd magemaker
+    ```
+  </Step>
+  <Step title="Install Runtime & Dev Dependencies">
+    ```bash
+    # main requirements + dev extras
+    pip install -e ".[dev]"
+    ```
+  </Step>
+  <Step title="Run Tests & Linters">
+    ```bash
+    pytest -q            # run unit + integration tests
+    black --check .      # format check
+    flake8               # style check
+    ```
+  </Step>
+  <Step title="Docs Preview (optional but recommended)">
+    ```bash
+    npm i -g mintlify   # once
+    mintlify dev        # hot-reload docs server
+    ```
+  </Step>
+</Steps>
+
+## Documentation Changes
+
+Magemaker’s docs are written in **MDX** and served by [Mintlify](https://mintlify.com/).
+
+1. New pages should live under an existing logical folder (e.g. `concepts/`, `tutorials/`) and be linked in `mint.json`.
+2. Use the existing front-matter style:
+   ```mdx
+   ---
+   title: Awesome Feature
+   description: Short description here
+   ---
+   ```
+3. Keep tone & components consistent (Cards, Steps, Notes, etc.).
+4. Run `mintlify dev` locally to preview.
+
+<Warning>
+  A PR that adds a new feature without updating docs **will not be merged**.
+</Warning>
+
+### Updating the API Reference
+The FastAPI server (see `server.py`) exposes REST routes such as `/chat/completions` and `/endpoint/{endpoint_name}`. If you modify or add routes, update `concepts/api.mdx` accordingly and include example requests.
+
+## Pull Request Checklist
+
+- <Icon icon="check" iconType="solid" /> Code builds & tests pass
+- <Icon icon="check" iconType="solid" /> New/updated tests added when appropriate
+- <Icon icon="check" iconType="solid" /> Docs updated (or not needed)
+- <Icon icon="check" iconType="solid" /> Follows [Conventional Commits](https://www.conventionalcommits.org/)
+
+## Commit Message Convention
+
+We follow the Conventional Commits spec:
+
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation only changes
+- `style:` Code style updates (formatting, missing semicolons, etc.)
+- `refactor:` Code change that neither fixes a bug nor adds a feature
+- `test:` Adding or correcting tests
+- `chore:` Other changes that don’t modify src or test files
+
+Example:
+```bash
+git commit -m "feat(api): add /v1/embeddings route"
+```
 
 ## License
 
-By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.
+By contributing, you agree that your contributions will be licensed under the **Apache 2.0 License**.
 
 ## Questions?
 
-Feel free to contact us at [support@slashml.com](mailto:support@slashml.com) if you have any questions about contributing!
+Feel free to contact us at [support@slashml.com](mailto:support@slashml.com) if you have any questions about contributing!
diff --git a/README.md b/README.md
@@ -1,24 +1,82 @@
-### These are docs for the [Magemaker-Docs](https://magemaker.slashml.com) documentation site.
+### Magemaker Documentation Repository
 
-The source code of magemaker is located at [Magemaker](https://github.com/slashml/magemaker)
+This repository contains the source files that power the public Magemaker docs site – [https://magemaker.slashml.com](https://magemaker.slashml.com).
 
-### Development
+If you are **updating or adding documentation** please work inside this repo, **not** the main `slashml/magemaker` code repository.
 
-Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command
+---
 
-```
-npm i -g mintlify
-```
+## Local Development
+
+Magemaker docs are built with **[Mintlify](https://docs.mintlify.com/)**. Use the Mintlify CLI to preview changes locally before you open a pull-request.
+
+1. Install the CLI (requires Node.js ≥ 16):
+
+   ```bash
+   npm install -g mintlify
+   ```
+
+2. From the root of this repository start the local dev server:
+
+   ```bash
+   mintlify dev
+   ```
+
+3. Open `http://localhost:3000` in your browser – changes hot-reload automatically.
+
+### Common Issues
 
-you need to have Node.js installed to use npm.
+| Symptom                                  | Fix                                              |
+| ---------------------------------------- | ------------------------------------------------- |
+| `mintlify` command not found             | Run `npm i -g mintlify`                           |
+| 404 when dev server starts               | Ensure you are in the folder that contains `mint.json` |
+| Build fails after adding new dependencies | Run `mintlify install` to regenerate the lock-file |
 
-Run the following command at the root of your documentation (where mint.json is)
+---
+
+## Folder Structure
 
 ```
-mintlify dev
+.
+├── about.mdx
+├── concepts/
+│   ├── api.mdx            # ← NEW – API reference for FastAPI proxy
+│   ├── deployment.mdx
+│   └── …
+├── configuration/
+│   └── …
+├── tutorials/
+│   └── …
+└── mint.json
 ```
 
-#### Troubleshooting
+*Pages inside `concepts`, `tutorials`, and `configuration` are automatically
+collected by Mintlify. When you add a new page remember to update the
+`navigation` section of **mint.json** so the page appears in the sidebar.*
+
+---
+
+## Adding / Updating Docs
+
+1. Create or edit an `.mdx` or `.md` file.
+2. Add front-matter:
+
+   ```yaml
+   ---
+   title: My New Page
+   description: Short one-sentence description
+   ---
+   ```
+
+3. Preview locally (`mintlify dev`) and confirm links / images work.
+4. If you introduced new functionality in `slashml/magemaker` **also add docs** for it here (see the newly-added `concepts/api.mdx` for an example).
+5. Commit using [Conventional Commits](https://www.conventionalcommits.org/) conventions, open a PR, and request review.
+
+---
+
+## Reference Links
 
-- Mintlify dev isn't running - Run `mintlify install` it'll re-install dependencies.
-- Page loads as a 404 - Make sure you are running in a folder with `mint.json`
+* Main codebase – <https://github.com/slashml/magemaker>
+* Live documentation – <https://magemaker.slashml.com>
+* Contribution guidelines – [`CONTRIBUTING.md`](./CONTRIBUTING.md)
+* **NEW** – FastAPI / OpenAI-style proxy reference – [`concepts/api.mdx`](./concepts/api.mdx)
diff --git a/about.mdx b/about.mdx
@@ -1,43 +1,64 @@
 ---
 title: About
-description: Deploy open source AI models to AWS, GCP, and Azure in minutes
+description: Deploy open-source AI models to AWS, GCP, and Azure in minutes
 "og:title": "Magemaker"
 ---
 
 ## About Magemaker
 
-Magemaker is a Python tool that simplifies the process of deploying open source AI models to your preferred cloud provider. Instead of spending hours digging through documentation, Magemaker lets you deploy Hugging Face models directly to AWS SageMaker, Google Cloud Vertex AI, or Azure Machine Learning.
+Magemaker is a Python tool that makes it **push-button simple** to deploy open-source AI models to your preferred cloud provider. Instead of spending hours digging through cloud docs, you can spin up Hugging Face models directly on:
 
-## What we're working on next
+- **AWS SageMaker**
+- **Google Cloud Vertex AI**
+- **Azure Machine Learning**
 
-- More robust error handling for various edge cases
-- Verbose logging
-- Enabling / disabling autoscaling
-- Enhanced multi-cloud support features
+### Key Features
 
-Do submit your feature requests at https://magemaker.featurebase.app/
+<CardGroup>
+  <Card title="Interactive CLI" icon="terminal">
+    Guided, menu-driven deployments – perfect for first-time users.
+  </Card>
+  <Card title="YAML-based IaC" icon="file-code">
+    Declarative configs for repeatable, CI-friendly deployments.
+  </Card>
+  <Card title="Fine-tuning" icon="wand-magic-sparkles">
+    Train and tune models with a single YAML file.
+  </Card>
+  <Card title="Multi-Cloud" icon="cloud">
+    One tool, three clouds. Mix-and-match providers as needed.
+  </Card>
+  <Card title="OpenAI-Compatible API" icon="plug">
+    Serve any deployed model behind an `/chat/completions` endpoint that works with the official *openai* Python SDK.
+  </Card>
+</CardGroup>
 
-## Known issues
+### What We're Working on Next
 
-- Querying within Magemaker currently only works with text-based models
-- Deleting a model is not instant, it may show up briefly after deletion
-- Deploying the same model within the same minute will break
-- Hugging-face models on Azure have different Ids than their Hugging-face counterparts. Follow the steps specified in the quick-start guide to find the relevant models
-- For Azure deploying models other than Hugging-face is not supported yet. 
-- Python3.13 is not supported because of an open-issue by Azure. https://github.com/Azure/azure-sdk-for-python/issues/37600
+- More robust error handling for edge cases
+- Verbose / structured logging
+- On-demand autoscaling controls
+- Additional multi-cloud utilities
+- Expanded model-type support (vision, audio, multimodal)
 
+Have a feature request? Let us know at [magemaker.featurebase.app](https://magemaker.featurebase.app/).
 
-If there is anything we missed, do point them out at https://magemaker.featurebase.app/
+### Known Issues
 
+1. Querying currently supports **text-based** models only.
+2. Endpoint deletion is asynchronous – an endpoint may appear for several minutes after deletion is requested.
+3. Deploying the **same endpoint name** within the same minute can fail (name collision).
+4. Hugging Face model **IDs differ on Azure** – follow the [Quick Start](/quick-start) guide to obtain the correct ID.
+5. Azure supports **Hugging Face models only** at the moment.
+6. Python 3.13 is not yet supported due to an [open Azure SDK issue](https://github.com/Azure/azure-sdk-for-python/issues/37600).
 
-## License
+If we missed something, please report it on [Featurebase](https://magemaker.featurebase.app/).
 
-Distributed under the Apache 2.0 License. See `LICENSE` for more information.
+### License
 
-## Contact
+Distributed under the Apache 2.0 License. See `LICENSE` for more information.
 
-You can reach us, faizan & jneid, at [faizan|jneid@slashml.com](mailto:support@slashml.com).
+### Contact
 
-You can give feedback at https://magemaker.featurebase.app/
+Questions or feedback? Reach out to **Faizan & Jneid** at [support@slashml.com](mailto:support@slashml.com).
 
-We'd love to hear from you! We're excited to learn how we can make this more valuable for the community and welcome any and all feedback and suggestions.
+We’d love to hear from you – community feedback drives our roadmap!