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 in the api_reference folder for more information.

Necessary

• NodeJS >= 18.0 (see the NodeJS documentation for installation instructions)
• (For building MDX files from .ipynb files) Python 3.9+, nbconvert, nbformat and pyyml

Optional

• (For building API docs) See doc-requirements.txt for API doc requirements.

$ npm install

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.

2. Run the development server:

$ npm start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Note: Some server-side rendering features will not work in this mode (e.g. the client redirects plugin). To test these, please use the "Build and Serve" workflow below.

In order to build the full MLflow documentation (i.e. the contents of https://mlflow.org/docs/latest/), please follow the following steps:

1. Run npm run build-api-docs in order to build the API reference and copy the generated HTML to static/api_reference. a. To speed up the build locally, you can run npm run build-api-docs:no-r to skip building R documentation
2. Run npm run convert-notebooks to convert .ipynb files to .mdx files. The generated files are git-ignored.
3. ⚠️ Important! Run export DOCS_BASE_URL=/docs/latest (or wherever the docs are expected to be served). This configures the Docusaurus baseUrl, and the site may not render correctly if this is improperly set.
4. Finally, run npm run build. This generates static files in the build directory, which can then be served.
5. (Optional) To serve the artifacts generated in the above step, run npm run serve.

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:

npm run build-all

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 and uploaded to the website.

This error occurs when some links in the sidebar point to non-existent documents.

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.

[ERROR] Error: Invalid sidebar file at "sidebarsGenAI.ts".
These sidebar document ids do not exist:

eval-monitor/notebooks/huggingface-evaluation-ipynb
eval-monitor/notebooks/question-answering-evaluation-ipynb
...