mxnet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Aaron Markham <aaron.s.mark...@gmail.com>
Subject Re: new website
Date Fri, 30 Aug 2019 00:57:47 GMT
pkgdown makes some nice looking R microsites. Good idea. Do you know
if many R users would still want the pdf or have things moved to use
websites for reference like this?
One of the nice things about the new pipelines for docs is that
they're not wrapped by Sphinx, so our R contributors will have an
easier time testing and adding this kind of feature.

On Thu, Aug 29, 2019 at 5:34 PM Yuan Tang <terrytangyuan@gmail.com> wrote:
>
> Thanks for the update, Aaron.
>
> Regarding the R docs, one suggestion I have is to use pkgdown package (
> https://pkgdown.r-lib.org/index.html) to automatically generated the
> documentation pages (tutorials, API reference, etc.). I've seen huge
> adoption of this package being used for documentations in the R community.
>
>
> On Thu, Aug 29, 2019 at 8:26 PM Aaron Markham <aaron.s.markham@gmail.com>
> wrote:
>
> > Hi everyone,
> >
> > I'm very excited to share a preview and the pull requests for a new
> > website and new documentation pipelines.
> >
> > The following link is using Apache's new staging site setup. It is
> > built from the new docs publishing pipelines in CI where a Jekyll
> > website is built, and documentation artifacts from Clojure, CPP, Java,
> > Julia, Python, R, and Scala are combined into one website.
> >
> > https://mxnet-beta.staged.apache.org
> >
> > It is the culmination of a lot of effort of several MXNet contributors.
> >
> > * A huge shout out goes to Thomas Delteil for the work on the new
> > Jekyll-backend and beautiful-looking website, and for helping me out
> > whenever I'd get stuck on revamping the 7 different API docs systems
> > in CI.
> > * Soji Adeshina and Vishaal Kapoor both helping me with the system
> > design for the new docs pipelines.
> > * Per Goncalves da Silva and Marco de Abreu both helped me with
> > figuring out CI issues.
> > * We also ported over Mu Li's beta site for the Python & R APIs which
> > had many contributors there. Thanks goes to Mu, Ivy Bazan, Jonas
> > Mueller, Aston Zhang, and Zhi Zhang for their help & contributions. I
> > apologize in advance if I missed anyone.
> >
> > Highlights:
> >
> > * R docs are now generated as part of CI. There were issues with R
> > docs coming from beta repo. They were not reproducible. So I began the
> > process of creating the pdf doc that is expected by R users as an
> > alternative. Thomas fixed a CPP bug that was blocking 90% of the docs
> > from appearing. The R docs are 10x in length compared to the pdf we're
> > hosting now!
> >
> > * Each other API is built in a micro-site fashion. You will notice
> > that the reference API links will open up the site that is generated
> > by that language's docs tools. We tried to keep the navigation common
> > and do this for the Python API. This is something that can be expanded
> > on for the other APIs in later updates to the website.
> >
> > * Each doc set can be generated separately with functions that will
> > run in Docker and generate the docs artifacts. This means you can now
> > focus on your preferred API and not have to deal with anything else.
> >
> > * Website changes are now much easier. You can serve Jekyll locally,
> > and have it do incremental updates, so you can see your changes live
> > without having to build MXNet or anything else. It's a pure front-end
> > setup.
> >
> > * For website publishing, the MXNet binary is built once and then
> > shared with the other docs generation pipelines.
> >
> > * For individual docs runs, you can run a "lite" binary build, then
> > follow it up with the docs run you want.
> >
> > ---
> >
> > For example to build MXNet:
> >
> > ci/build.py --docker-registry mxnetcidev --platform ubuntu_cpu_lite
> > /work/runtime_functions.sh build_ubuntu_cpu_docs
> >
> > Then to build the R docs:
> >
> > ci/build.py --docker-registry mxnetcidev --platform ubuntu_cpu_r
> > /work/runtime_functions.sh build_r_docs
> >
> > There is now a Docker image and a runtime_function for each API
> > (except Perl which is built offsite). Python is like this:
> >
> > ci/build.py --docker-registry mxnetcidev --platform ubuntu_cpu_python
> > /work/runtime_functions.sh build_python_docs
> >
> > The pattern for platform is ubuntu_cpu_{api} and runtime_functions.sh
> > is build_{api}_docs.
> >
> > Further information is on the developer wiki:
> > https://cwiki.apache.org/confluence/display/MXNET/Building+the+New+Website
> > ----
> >
> > Ok, now this is where YOU come in. We need reviewers and testers.
> >
> > There are a lot of changes. My original PR was over 1,000 files with
> > 83k additions and 55k deletions. So, Thomas broke this up into three
> > pull requests that stack.
> >
> > Step 1 New Content https://github.com/apache/incubator-mxnet/pull/15884
> > Step 2 Remove Old Content
> > https://github.com/apache/incubator-mxnet/pull/15885
> > Step 3 Setup New Jenkins
> > https://github.com/apache/incubator-mxnet/pull/15886
> >
> > For reviewing purposes, start with the new content - what's easily
> > visible on the preview website. This is mostly happening in the first
> > PR:
> > https://github.com/apache/incubator-mxnet/pull/15884
> > You can also look at these helper PRs that show you the differences so
> > it is easier to review what's happening in Steps 2 and 3. You can
> > review these now as well.
> > Step 1->2: https://github.com/ThomasDelteil/incubator-mxnet/pull/5
> > Step 2->3: https://github.com/ThomasDelteil/incubator-mxnet/pull/6
> >
> > I really appreciate everyone's support on this effort.
> >
> > Cheers,
> > Aaron
> >

Mime
View raw message