You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mxnet.apache.org by GitBox <gi...@apache.org> on 2019/03/05 01:55:28 UTC
[GitHub] [incubator-mxnet] astonzhang opened a new issue #14330: [RFC][WIP]
Integrating the new MXNet website
astonzhang opened a new issue #14330: [RFC][WIP] Integrating the new MXNet website
URL: https://github.com/apache/incubator-mxnet/issues/14330
# About the new website
We heard of complaints and suggestions on the contents and UX of the MXNet website such as poor-quality tutorial examples and lack of feedback providing channel (e.g., https://github.com/apache/incubator-mxnet/issues/6493 and https://github.com/apache/incubator-mxnet/issues/12610). To make improvements on such, we propose to re-design the MXNet website.
The new website (WIP) will be published at http://beta.mxnet.io. We expect that the new website and the old website http://mxnet.incubator.apache.org/ will co-exist for some time until the old website can be completely replaced by the new website.
# Proposed major changes
Below are proposed major new changes.
## Design
1. We document each class or method in its own page to reduce the loading time. A TOC appears on the right hand side to allow users to navigate through different classes and methods.
2. We add disqus at the bottom of almost every page to allow users to comment and discuss.
3. We change the sphinx theme based on [the material design](https://getmdl.io/), which has a modern look.
## Content
1. We rely on the ecosystem of MXNet. Thus, we keep deep learning algorthm specific tutorials in [Dive into Deep Learning](www.d2l.ai), and keep toolkit-specific tutorials in the respective toolkit website/repo, such as [GluonCV](https://gluon-cv.mxnet.io) and [GluonNLP](http://gluon-nlp.mxnet.io/).
2. For each programming laungage in the new website, we re-organize documentation into two directories: `guide/` for tutorials and `api/` for API references.
3. To improve quality of the documentation, we are also revising tutorials under `guide/`.
4. We highlight the use of Gluon.
## Building process (learn more in Appendix A)
The new website (http://beta.mxnet.io) is currently built from https://github.com/mli/new-docs (hereinafter referred to as **new-docs repo**). As we will integrate the new-docs repo into the MXNet repo, the building process of the new website is subject to change (WIP).
1. We use conda to manage environments of dependencies.
2. Tutorials are written in markdown files. They will be converted to ipynb and get evaluated to generate outputs when the website is built. The dependencies for evaluating tutorials are specified in the conda environment.
If you are interested in more details about what's new in the new website, just check out [this wiki](https://github.com/mli/new-docs/wiki/What's-new) written by @mli.
## Status (will be updated)
1. The new website can be previewed at http://beta.mxnet.io.
2. Website redesign & wireframe are proposed at https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=103089084
3. We plan to open a feature branch to facilitate the integration of the new-docs repo.
4. To ensure high quality of contents, we plan to focus on a minimum viable product (MVP) in the initial release. The MVP may contain Python docs only. A proposed list of Python tutorials under `guide/` in the initial release can be found in Appendix B. We will gradually add back other tutorials and docs of the other programming languages from the old website after the initial release.
5. We are revising contents of tutorials and open PRs can be found [here](https://github.com/mli/new-docs/pulls). Feel free to review and comment these PRs.
# Appendix A: Building process
In the following, we detail the building process at the new-docs repo. The building process of the new website is subject to change when we integrate the new-docs repo into the MXNet repo.
## Overview
1. A pull request will trigger the execution of Jenkinsfile.
2. When Jenkinsfile is executed:
1. Install all dependencies as specified in environment.yml, the environment is called mxnet-docs. The environment is managed by conda.
2. Build Python docs in build/html (See details below)
3. Build R docs in build/html/r
4. If the pull request is merged to the master branch, it then executes build/upload_doc.sh to upload all files under build/html to s3://beta.mxnet.io
## Building Python docs
It is by executing python/build_doc.sh.
1. When the mxnet-docs environment is activated, it will invoke python/Makefile to *"make html"*:
1. When making dependencies of html, Python tutorials will be converted from markdown to ipynb and get evaluated.
2. When *"make html"*, python/build/Makefile will be invoked to *"make html"* as well:
1. It will use [*sphinx-build*](https://www.sphinx-doc.org/en/master/man/sphinx-build.html) command to generate all the html/css/js files in python/build/_build/html according to user-defined configurations at python/build/conf.py
1. conf.py specifies the master doctree document for organizing htmls (python/index.rst)
2. Move python/build/_build/html to build/html.
## Building R docs (or another language)
The building process is similar to that of building Python docs.
# Appendix B: Proposed list of Python tutorials in the MVP
Items below are usually the names of the existing files. For instance, `1-ndarray` refers to <https://github.com/mli/new-docs/blob/master/python/guide/crash-course/1-ndarray.md>. If such a file does not exist, such as Symbol, we will create it.
- Getting Started
- A 60-minute crash course
- 1-ndarray
- 2-nn
- 3-autograd
- 4-train
- 5-predict
- 6-use_gpus
- Moving from other DL frameworks
- to-mxnet/pytorch.html
- to-mxnet/tf.html
- Packages and Modules
- ndarray
- ndarray (need more details, refer to <https://en.d2l.ai/chapter_crashcourse/ndarray.html>)
- sparse
- autograd (need more details)
- Using GPU (refer to <https://en.d2l.ai/chapter_deep-learning-computation/use-gpu.html>)
- optimizer
- lr_scheduler
- Symbol
- gluon
- nn (need more details, refer to <https://en.d2l.ai/chapter_deep-learning-computation/model-construction.html>)
- parameters (need more details, refer to <https://en.d2l.ai/chapter_deep-learning-computation/parameters.html>)
- init (need more details, refer to <https://en.d2l.ai/chapter_deep-learning-computation/parameters.html> and <https://en.d2l.ai/chapter_deep-learning-computation/deferred-init.html>)
- custom-layer (need more details, refer to <https://en.d2l.ai/chapter_deep-learning-computation/custom-layer.html>)
- data
- image_augmentation (should show how to use gluon.data.vision.transforms.Compose, refer to <https://en.d2l.ai/chapter_computer-vision/image-augmentation.html>)
- file I/O (refer to <https://en.d2l.ai/chapter_deep-learning-computation/read-write.html>)
- loss (should explain how to create customized loss)
- trainer
- hybridize (need more details, refer to <https://en.d2l.ai/chapter_computational-performance/hybridize.html>)
- model_zoo
- Performance
- Essentials
- (optional) perf
- profiler
- Compression
- float16
- (optional) int8
- Accelerated Backend
- (optional) tensor-rt
- Deployment
- Deploy into Another Language
- cpp
- scala/java
- ONNX
- Customization (extend)
- customop (should address customer complaints: <https://discuss.gluon.ai/t/topic/10822>)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services