[FR] [Roadmap] Embed examples into documentation

BenWilson2 commented 2 years ago

MLflow Roadmap Item

This is an MLflow Roadmap item that has been prioritized by the MLflow maintainers. We’ve identified this feature as a highly requested addition to the MLflow package based on community feedback. We're seeking a community contribution for the implementation of this feature and will enthusiastically support the development and review of a submitted PR for this.

Contribution Note

As with other roadmap items, there may be a desire for multiple contributors to work on an issue. While we don’t discourage collaboration, we strongly encourage that a primary contributor is assigned to roadmap issues to simplify the merging process. The items on the roadmap are of a high priority. Due to the wide-spread demand of roadmap features, we encourage potential contributors to only agree to take on the work of creating a PR, making changes, and ensuring that test coverage is adequately created for the feature if they are willing and able to see the implementation through to a merged state.

Feature scope

This roadmap feature’s complexity is classified as:

[X] good-first-issue: This feature is limited in complexity and effort required to implement.
[ ] simple: This feature does not require a large amount of effort to implement and / or is clear enough to not need a design discussion with maintainers.
[ ] involved: This feature will require a substantial amount of development effort but does not require an agreed-upon design from the maintainers. The feedback given during the PR phase may be involved and necessitate multiple iterations before approval. (Please bear with us as we collaborate with you to make a great contribution)
[ ] design-recommended: This is a substantial feature that should have a design document approved prior to working on an implementation (to save your time, not ours). After agreeing to work on this feature, a maintainer will be assigned to support you throughout the development process.

Proposal Summary

Currently, the examples page within the docs provides links to the files within Github, reducing the utility of the tutorials and examples that currently exist. This FR is intended to convert this design to an inline display of example code that can be explained and referenced with walkthrough explanations of the functionality shown. For a reference of what this should be converted to, see the docs for diviner. The inline code examples to create this display are here.

Note that some additional dependencies will be required to be added here to give sphinx the ability to render jupyter notebooks (nbsphinx) and other features requiring pandoc.

In the process of creating these pages, a full walkthrough of what the rendered script is, as well as additional guidance on its use and any further anecdotal comments about what it is showing will be enthusiastically welcomed.

Motivation

What is the use case for this feature?

Add a more thorough examples and tutorials section that can help new users get started with MLflow.

Why is this use case valuable to support for MLflow users in general? ^

What component(s), interfaces, languages, and integrations does this feature affect?

Components

[ ] area/artifacts: Artifact stores and artifact logging
[ ] area/build: Build and test infrastructure for MLflow
[X] area/docs: MLflow documentation pages
[X] area/examples: Example code
[ ] area/model-registry: Model Registry service, APIs, and the fluent client calls for Model Registry
[ ] area/models: MLmodel format, model serialization/deserialization, flavors
[ ] area/projects: MLproject format, project running backends
[ ] area/scoring: MLflow Model server, model deployment tools, Spark UDFs
[ ] area/server-infra: MLflow Tracking server backend
[ ] area/tracking: Tracking Service, tracking client APIs, autologging

Interfaces

[ ] area/uiux: Front-end, user experience, plotting, JavaScript, JavaScript dev server
[ ] area/docker: Docker use across MLflow's components, such as MLflow Projects and MLflow Models
[ ] area/sqlalchemy: Use of SQLAlchemy in the Tracking Service or Model Registry
[ ] area/windows: Windows support

Languages

[ ] language/r: R APIs and clients
[ ] language/java: Java APIs and clients
[ ] language/new: Proposals for new client languages

Integrations

[ ] integrations/azure: Azure and Azure ML integrations
[ ] integrations/sagemaker: SageMaker integrations
[ ] integrations/databricks: Databricks integrations

BenWilson2 commented 2 years ago

For any questions, concerns, or clarification on implementing this issue, please ping @BenWilson2

architsinghal-mriirs commented 2 years ago

Hi @BenWilson2. I'd like to collaborate and take up this issue. You can add me as the primary contributor. Thanks and Regards Archit Singhal

vishnurvn commented 2 years ago

Hi @BenWilson2, diviner documentation and the current MLFlow documentation look similar in explaining the concepts. The difference is, that there are fewer comments in the MLFlow documentation. The idea behind this FR is to split the file into chunks and explain them individually? I think I'm missing something here. Would be great if you can provide some clarifications.

tiagotele commented 1 year ago

Hey there! I would like to contribute here!

BenWilson2 commented 1 year ago

@tiagotele sounds great! Feel free to select a flavor and draft up a notebook example that showcases full use of MLflow and the respective flavor for logging metrics, parameters, tags, registering a model, etc :) We'll work together on getting the Examples page in the documentation reworked to support the display of it!

tiagotele commented 1 year ago

@tiagotele sounds great! Feel free to select a flavor and draft up a notebook example that showcases full use of MLflow and the respective flavor for logging metrics, parameters, tags, registering a model, etc :) We'll work together on getting the Examples page in the documentation reworked to support the display of it!

Ok. I'll start it and post here when I have updates/questions.

tiagotele commented 1 year ago

Hi there.

@BenWilson2 I have few questions about the output of this FR:

@architsinghal-mriirs and @vishnurvn are still working here?
I also have the same questions that @vishnurvn did above.
Should I add new documentation pages with every example in the example folder?
Should I parse the current examples to this new rendering mechanism with sphinx?

JaynouOliver commented 1 year ago

Hey there, I would like to contribute here. Can you please assign me as a contributor for this issue? I am also available to collaborate and do the work if needed. I am passionate about learning this. I hope my skills will help you!

JaynouOliver commented 1 year ago

Hey there, I would like to contribute here. Can you please assign me as a contributor for this issue? I am also available to collaborate and do the work if needed. I am passionate about learning this. @BenWilson2

mlflow / mlflow