README.md
1 # MLflow Documentation 2 3 This README covers information about the main MLflow documentation. The API reference is built separately and included as a static folder during the full build process. Please check out the [README](https://github.com/mlflow/mlflow/blob/master/docs/api_reference/README.md) in the `api_reference` folder for more information. 4 5 ## Prerequisites 6 7 **Necessary** 8 9 - NodeJS >= 18.0 (see the [NodeJS documentation](https://nodejs.org/en/download) for installation instructions) 10 - (For building MDX files from `.ipynb` files) Python 3.9+, [nbconvert](https://pypi.org/project/nbconvert/), [nbformat](https://pypi.org/project/nbformat/) and [pyyml](https://pypi.org/project/pyyml/) 11 12 **Optional** 13 14 - (For building API docs) See [doc-requirements.txt](https://github.com/mlflow/mlflow/blob/master/requirements/doc-requirements.txt) for API doc requirements. 15 16 ## Installation 17 18 ```shell 19 npm install 20 ``` 21 22 ## Local Development 23 24 1. If you haven't done this before, run `npm run convert-notebooks` to convert `.ipynb` files to `.mdx` files. The generated files are git-ignored. 25 26 2. Run the development server: 27 28 ```shell 29 npm start 30 ``` 31 32 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. 33 34 **Note**: Some server-side rendering features will not work in this mode (e.g. the [client redirects plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-client-redirects)). To test these, please use the "Build and Serve" workflow below. 35 36 ## Build and Serve 37 38 In order to build the full MLflow documentation (i.e. the contents of https://mlflow.org/docs/latest/), please follow the following steps: 39 40 1. Run `npm run build-api-docs` in order to build the API reference and copy the generated HTML to `static/api_reference`. 41 a. To speed up the build locally, you can run `npm run build-api-docs:no-r` to skip building R documentation 42 2. Run `npm run convert-notebooks` to convert `.ipynb` files to `.mdx` files. The generated files are git-ignored. 43 3. **⚠️ Important!** Run `export DOCS_BASE_URL=/docs/latest` (or wherever the docs are expected to be served). This configures the [Docusaurus baseUrl](https://docusaurus.io/docs/api/docusaurus-config#baseUrl), and the site may not render correctly if this is improperly set. 44 4. Finally, run `npm run build`. This generates static files in the `build` directory, which can then be served. 45 5. (Optional) To serve the artifacts generated in the above step, run `npm run serve`. 46 47 ## Building for release 48 49 The generated `build` folder is expected to be hosted at https://mlflow.org/docs/latest. However, as our docs are versioned, we also have to generate the documentation for `https://mlflow.org/docs/{version}`. To do this conveniently, you can run the following command: 50 51 ``` 52 npm run build-all 53 ``` 54 55 This command will run all the necessary steps from the "Build and Serve" workflow above, and set the correct values for `DOCS_BASE_URL`. The generated HTML will be dumped to `build/latest` and `build/{version}`. These two folders can then be copied to the [docs repo](https://github.com/mlflow/mlflow-legacy-website/tree/main/docs) and uploaded to the website. 56 57 ## Troubleshooting 58 59 ### `Error: Invalid sidebar file at "sidebarsGenAI.ts". These sidebar document ids do not exist:` 60 61 This error occurs when some links in the sidebar point to non-existent documents. 62 63 When it errors for `-ipynb` pages, it is not the link problem but the notebook conversion script is not run. Run `npm run convert-notebooks` in the above steps to convert `.ipynb` files to `.mdx` files. The generated files are git-ignored. 64 65 ``` 66 [ERROR] Error: Invalid sidebar file at "sidebarsGenAI.ts". 67 These sidebar document ids do not exist: 68 69 eval-monitor/notebooks/huggingface-evaluation-ipynb 70 eval-monitor/notebooks/question-answering-evaluation-ipynb 71 ... 72 ```