Regenerates R API docs & adds instructions for updating R documentati…

…on when making API changes (mlflow#1124)

Regenerates R API docs, and adds a bash script + instructions for regenerating R API docs to our contributor guide.

CONTRIBUTING.rst

@@ -11,7 +11,9 @@ tracking, and model APIs.
 Prerequisites
 ~~~~~~~~~~~~~
 
-We recommend installing MLflow in its own conda environment for development, as follows:
+First, install the Python MLflow package from source - this is required for developing & testing
+changes across all languages and APIs. We recommend installing MLflow in its own conda environment
+by running the following from your checkout of MLflow:
 
 .. code-block:: bash
 
@@ -26,6 +28,14 @@ We recommend installing MLflow in its own conda environment for development, as
 You can verify that ``npm`` is on the PATH by running ``npm -v``, and
 `install npm <https://www.npmjs.com/get-npm>`_ if needed.
 
+If contributing to MLflow's R APIs, install `R <https://cloud.r-project.org/>`_. For changes to R
+documentation, also install `pandoc <https://pandoc.org/installing.html>`_ 2.2.1 or above,
+verifying the version of your installation via ``pandoc --version``.
+
+If contributing to MLflow's Java APIs or modifying Java documentation,
+install `Java <https://www.java.com/>`_ and `Apache Maven <https://maven.apache.org/download.cgi>`_.
+
+
 Install Node Modules
 ~~~~~~~~~~~~~~~~~~~~
 Before running the Javascript dev server or building a distributable wheel, install Javascript
@@ -58,6 +68,10 @@ and `install <https://maven.apache.org/install.html>`_ Maven. You can then build
   cd mlflow/java
   mvn compile test
 
+If opening a PR that makes API changes, please regenerate API documentation as described in
+`Writing Docs`_ and commit the updated docs to your PR branch.
+
+
 R
 -
 
@@ -103,6 +117,9 @@ Run linter:
   Rscript -e 'lintr::lint_package()'
 
 
+If opening a PR that makes API changes, please regenerate API documentation as described in
+`Writing Docs`_ and commit the updated docs to your PR branch.
+
 When developing, you can make Python changes available in R by running (from mlflow/R/mlflow):
 
 .. code-block:: bash
@@ -152,6 +169,9 @@ exclude:
     localhost be enabled, and can be run via ``pytest --requires-ssh``.
   - Tests marked with @pytest.mark.release. These tests can be run via ``pytest --release``.
 
+If opening a PR that changes or adds new APIs, please update or add Python documentation as
+described in `Writing Docs`_ and commit the docs to your PR branch.
+
 
 Building Protobuf Files
 -----------------------
@@ -229,9 +249,43 @@ Build a pip-installable wheel in ``dist/``:
 
 Writing Docs
 ------------
-Install the necessary Python dependencies via ``pip install -r dev-requirements.txt``. Then run
+First, install dependencies for building docs as described in `Prerequisites`_.
+
+To generate a live preview of Python & other rst documentation, run the following snippet. Note
+that R & Java API docs must be regenerated separately after each change and are not live-updated;
+see subsequent sections for instructions on generating R and Java docs.
 
 .. code-block:: bash
 
    cd docs
    make livehtml
+
+
+Generate R API rst doc files via:
+
+.. code-block:: bash
+  cd docs
+  make rdocs
+
+Generate Java API rst doc files via:
+
+.. code-block:: bash
+  cd docs
+  make javadocs
+
+
+Generate API docs for all languages via:
+
+.. code-block:: bash
+  cd docs
+  make html
+
+
+If changing existing Python APIs or adding new APIs under existing modules, ensure that references
+to the modified APIs are updated in existing docs under ``docs/source``. Note that the Python doc
+generation process will automatically produce updated API docs, but you should still audit for
+usages of the modified APIs in guides and examples.
+
+If adding a new public Python module, create a corresponding doc file for the module under
+``docs/source/python_api`` - `see here <https://github.com/mlflow/mlflow/blob/v0.9.1/docs/source/python_api/mlflow.tracking.rst#mlflowtracking>`_
+for an example.

dev-requirements.txt

@@ -1,8 +1,8 @@
 # Dev/Deployment
 sphinx==1.7.9
-sphinx_rtd_theme
-sphinx-autobuild
-sphinx-click
+sphinx_rtd_theme==0.4.3
+sphinx-autobuild==0.7.1
+sphinx-click==2.1.0
 nose
 codecov
 coverage

docs/Makefile

@@ -56,10 +56,17 @@ help:
 clean:
 	rm -rf $(BUILDDIR)/*
 
+.PHONY: javadocs
+javadocs:
+	./build-javadoc.sh
+
+.PHONY: rdocs
+rdocs:
+	./build-rdoc.sh
+
 .PHONY: html
-html:
+html: javadocs rdocs
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	./build-javadoc.sh
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 

docs/build-rdoc.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -ex
+pushd ../mlflow/R/mlflow
+Rscript -e 'install.packages("devtools", repos = "https://cloud.r-project.org")'
+Rscript -e 'devtools::install_dev_deps(dependencies = TRUE)'
+Rscript -e 'install.packages("Rd2md", repos = "https://cloud.r-project.org")'
+Rscript -e 'install.packages("rmarkdown", repos = "https://cloud.r-project.org")'
+rm -rf man
+Rscript -e "roxygen2::roxygenise()"
+Rscript document.R
+popd