You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: CONTRIBUTING.md
+9-73
Original file line number
Diff line number
Diff line change
@@ -831,87 +831,23 @@ We use [taplo](https://taplo.tamasfe.dev/) to enforce consistent TOML formatting
831
831
832
832
### Writing Docs
833
833
834
-
First, install dependencies for building docs as described in [Environment Setup and Python configuration](#environment-setup-and-python-configuration).
834
+
There are two separate build systems for the MLflow documentation:
835
835
836
-
Building documentation requires [Pandoc](https://pandoc.org/index.html). It should have already been
837
-
installed if you used the automated env setup script
but if you are manually installing dependencies, please follow [the official instruction](https://pandoc.org/installing.html).
836
+
#### API Docs
840
837
841
-
Also, check the version of your installation via `pandoc --version` and ensure it is 2.2.1 or above.
842
-
If you are using Mac OSX, be aware that the Homebrew installation of Pandoc may be outdated. If you are using Linux,
843
-
you should use a deb installer or install from the source, instead of running `apt` / `apt-get` commands. Pandoc package available on official
844
-
repositories is an older version and contains several bugs. You can find newer versions at <https://github.com/jgm/pandoc/releases>.
838
+
The [API reference](https://mlflow.org/docs/latest/api_reference/) is managed by [Sphinx](https://www.sphinx-doc.org/en/master/). The content is primarily populated by our Python docstrings, which are written in reStructuredText (RST).
845
839
846
-
To generate a live preview of Python & other rst documentation, run the
847
-
following snippet. Note that R & Java API docs must be regenerated
848
-
separately after each change and are not live-updated; see subsequent
849
-
sections for instructions on generating R and Java docs.
840
+
For instructions on how to build the API docs, please check the [README.md](https://github.com/mlflow/mlflow/blob/master/docs/api_reference/README.md) in the `docs/api_reference/` subfolder.
850
841
851
-
```bash
852
-
cd docs
853
-
make livehtml
854
-
```
855
-
856
-
Generate R API rst doc files via:
857
-
858
-
```bash
859
-
cd docs
860
-
make rdocs
861
-
```
862
-
863
-
---
842
+
#### Main Docs
864
843
865
-
**NOTE**
844
+
The main MLflow docs (e.g. feature docs, tutorials, etc) are written using [Docusaurus](https://docusaurus.io/). The only prerequisite for building these docs is NodeJS >= 18.0. Please check out the [official NodeJS docs](https://nodejs.org/en/download) for platform-specific installation instructions.
866
845
867
-
If you attempt to build the R documentation on an ARM-based platform (Apple silicon M1, M2, etc.)
868
-
you will likely get an error when trying to execute the Docker build process for the make command.
869
-
To address this, set the default docker platform environment variable as follows:
846
+
To get started, simply run `yarn && yarn start` from the [`docs/`](https://github.com/mlflow/mlflow/blob/master/docs/) folder. This will spin up a development server that can be viewed at `http://localhost:3000/` (by default). The source files (primarily `.MDX`) are located in the [`docs/docs/`](https://github.com/mlflow/mlflow/blob/master/docs/docs/) subfolder. Changes to these files should be automatically reflected in the development server!
870
847
871
-
```bash
872
-
export DOCKER_DEFAULT_PLATFORM=linux/amd64
873
-
```
874
-
875
-
---
876
-
877
-
Generate Java API rst doc files via:
878
-
879
-
```bash
880
-
cd docs
881
-
make javadocs
882
-
```
848
+
There are also some `.ipynb` files which serve as the source for some of our tutorials. These are converted to MDX via a custom script (`yarn convert-notebooks`). If you want to make changes to these, you will need to install the `nbconvert` Python package in order to preview your changes.
883
849
884
-
Generate API docs for all languages via:
885
-
886
-
```bash
887
-
cd docs
888
-
make html
889
-
```
890
-
891
-
Generate only the main .rst based documentation:
892
-
893
-
```bash
894
-
cd docs
895
-
make rsthtml
896
-
```
897
-
898
-
If changing existing Python APIs or adding new APIs under existing
899
-
modules, ensure that references to the modified APIs are updated in
900
-
existing docs under `docs/source`. Note that the Python doc generation
901
-
process will automatically produce updated API docs, but you should
902
-
still audit for usages of the modified APIs in guides and examples.
903
-
904
-
If adding a new public Python module, create a corresponding doc file
905
-
for the module under `docs/source/python_api` - [see
> Note: If you are experiencing issues with rstcheck warning of failures in files that you did not modify, try:
910
-
911
-
```bash
912
-
cd docs
913
-
make clean; make html
914
-
```
850
+
For more detailed information, please check the [README.md](https://github.com/mlflow/mlflow/blob/master/docs/README.md) in the `docs/` folder. We're looking forward to your contributions!
The `docusaurus` branch is the working branch for all Docusaurus migration work. We are switching away from Sphinx for our main informational docs, and using [Docusaurus](https://docusaurus.io/) instead.
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
4
5
-
## Jobs to be Done
5
+
## Prerequisites
6
6
7
-
1. Migrating all non-API related docs from `.rst` to `.mdx`, the Docusaurus format
8
-
a. These files can be found in the `rst_to_migrate` folder
9
-
2. Migrating notebooks to be rendered via [this plugin](https://github.com/datalayer/jupyter-ui/tree/main/packages/docusaurus-plugin), rather than by `nbsphinx`
10
-
a. Notebooks are also found in the `rst_to_migrate` folder, but will end in `.ipynb`
7
+
**Necessary**
8
+
- NodeJS >= 18.0 (see the [NodeJS documentation](https://nodejs.org/en/download) for installation instructions)
11
9
12
-
### Installation
10
+
**Optional**
11
+
- (For building MDX files from `.ipynb` files) Python 3.9+ and [nbconvert](https://pypi.org/project/nbconvert/).
12
+
- (For building API docs) See [doc-requirements.txt](https://github.com/mlflow/mlflow/blob/master/requirements/doc-requirements.txt) for API doc requirements.
13
+
14
+
## Installation
13
15
14
16
```
15
17
$ yarn
16
18
```
17
19
18
-
###Local Development
20
+
## Local Development
19
21
20
22
```
21
23
$ yarn start
22
24
```
23
25
24
26
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
25
27
26
-
### Build
27
-
28
-
```
29
-
$ yarn build
30
-
```
31
-
32
-
This command generates static content into the `build` directory and can be served using any static contents hosting service.
33
-
34
-
### Formatting
35
-
36
-
```
37
-
$ yarn format
38
-
```
39
-
40
-
This command automatically formats all `.mdx` files within the `/docs` folder
41
-
42
-
43
-
### Deployment
28
+
**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.
44
29
45
-
Using SSH:
30
+
## Build and Serve
46
31
47
-
```
48
-
$ USE_SSH=true yarn deploy
49
-
```
50
-
51
-
Not using SSH:
52
-
53
-
```
54
-
$ GIT_USER=<Your GitHub username> yarn deploy
55
-
```
32
+
In order to build the full MLflow documentation (i.e. the contents of https://mlflow.org/docs/latest/), please follow the following steps:
56
33
57
-
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
34
+
1. Run `yarn build-api-docs` in order to build the API reference and copy the generated HTML to `static/api_reference`.
35
+
a. To speed up the build locally, you can run `yarn build-api-docs:no-r` to skip building R documentation
36
+
2. Run `yarn convert-notebooks` to convert `.ipynb` files to `.mdx` files. The generated files are git-ignored.
37
+
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.
38
+
4. Finally, run `yarn build`. This generates static files in the `build` directory, which can then be served.
39
+
5. (Optional) To serve the artifacts generated in the above step, run `yarn serve`.
This directory contains the MLflow API reference. The source code (`.rst` files) is relatively minimal, as the API docs are mainly populated by docstrings in the MLflow Python source.
4
+
5
+
## Building the docs
6
+
7
+
First, install dependencies for building docs as described in the [Environment Setup and Python configuration](https://github.com/mlflow/mlflow/blob/master/CONTRIBUTING.md#environment-setup-and-python-configuration) section of the main MLflow contribution guide.
8
+
9
+
Building documentation requires [Pandoc](https://pandoc.org/index.html). It should have already been
10
+
installed if you used the automated env setup script
0 commit comments