mxnet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thomas DELTEIL <thomas.delte...@gmail.com>
Subject Re: new website, docs code freeze
Date Sat, 21 Sep 2019 04:28:33 GMT
Thanks all for the feedback,

We'll send an email next week with the list of missing features, content
and bugs that we plan to fix.
We took the option of releasing early, with some features missing, rather
than trying to be at feature parity with the old website before launching
the website.
The reason why we decided to do that is two-fold:
- playing catch-up with docs in master introduce daily conflicts that need
to be resolved and introduce opportunity for errors
- by releasing early, we can take advantage of the community contributions
in modifying whatever the community feels like a better way of doing things.

One of the goals of the new website was to disentangle the main website,
now called "static_site" to the auto-generated docs. Now the overall site
is made of a main static site, with easy to modify content and easy to
understand architecture for anybody familiar with basic html, and a
collection of mini-websites for each language bindings that can be built in
isolation and that are self-contained. Actually the new CI jobs builds all
of them in parallel independently.

There is PLENTY of room for improvement, it would be great if the community
can help contribute to bring the new website at the same level of content
richness as the old one, and then even further.

Missing features:
- As pointed by Haibin, the API docs do not have the full list of operators
and classes. There is a mix of auto-generated docs based on packages, and
some docs that are spelled out manually to improve the logical organization
of the package where there is a need. The drawback with manually listed
classes in a package is that it's very easy to miss some. If someone wanted
to build a sanity check that would automatically detect which classes are
not in the documentation, or if someone knew how to enable that with
sphinx, that would be a great addition to the python docs
- There is missing content in the python tutorials, and the discoverability
could be improved. Some old tutorials have not been migrated just yet.
- The nightly tests on tutorials have been disabled for now
- There is no "Download jupyter notebook" for tutorials just yet.
- Non-python tutorials might benefit from a blurb description and a better
content organization.
- Python tutorials could be better organized, have a picture accompanying
their description
- There is no site-wide search, this is not an easy problem to solve to be
fair given the static nature of the website, but maybe an external plugin
might be able to give a half-way solution
- There is no version selector for the docs
- There is bug in search box of the python docs, but this is just a small
JS bug that can be fixed easily (on my list for next week)
- Most old links have not had a redirect put in place.

We'll formalize this in github issues next week, but they are all fairly
small and helping out on these would be a great way of familiarizing
yourself with the new website build system and website architecture.

 Thanks all for the feedback, please keep it coming!

Thomas Delteil

Le sam. 21 sept. 2019 à 09:53, Haibin Lin <haibin.lin.aws@gmail.com> a
écrit :

> It looks like my previous email did not go through. Re-sending:
>
> Hi Aaron,
>
> The website looks cool. Thanks for pushing this to production. A few
> questions:
>
> - I was looking for the API doc for mx.sym.dot, but I find that most
> operators under mx.sym.* are missing. Is this expected?
> - I was also checking the search functionality, searching the keyword
> "ndarray" only returns one result "mxnet.ndarray.NDArray", which doesn't
> seem right. There animation keeps going (Searching. -> Searching.. ->
> Searching ...) and gives me an impression that the search is never
> completely done(?).
>
> Best,
> Haibin
>
>
> On Fri, Sep 20, 2019 at 4:50 PM Chaitanya Bapat <chai.bapat@gmail.com>
> wrote:
>
> > Thanks Aaron and the team for launching new website!
> >
> > 1. There's no search button anywhere on the landing page.
> > 2. I wasn't able to find FAQ (and without search button I dont have
> option
> > but to go manually on each menu). Only when I go to Docs&Tutorials -> FAQ
> > -> Extend and Cotribute (that I got what I wanted).
> >
> > Suggestions
> > Might want to make this searchable and pop FAQ on the main page (or
> > somewhere prominent)
> >
> > Thanks,
> > Chai
> >
> >
> > On Fri, 20 Sep 2019 at 14:58, Przemysław Trędak <ptrendx@apache.org>
> > wrote:
> >
> > > There seems to be a problem with (at least Python, did not check
> others)
> > > APIs. For example this page:
> > >
> > >
> >
> https://mxnet.incubator.apache.org/api/python/docs/api/symbol/_autogen/mxnet.symbol.Symbol.argmax.html
> > >
> > > says that it is a convenience method for argmax (with a link), but
> > > clicking that link just points to the same website (and so user has no
> > way
> > > of getting to the docs of the actual operator).
> > >
> > > When I tried to manually remove Symbol from the URL to get to
> > > mxnet.symbol.argmax.html, I got a "Not found" webpage which I guess
> also
> > > should not happen (ignoring the fact that this should exist, going to
> > > random URL under the website should redirect to the main page I think).
> > >
> > > Przemek
> > >
> > > On 2019/09/20 16:41:28, Lin Yuan <apeforest@gmail.com> wrote:
> > > > Looks very neat. Thank you Aaron and many others for launching this!
> > > >
> > > > On Fri, Sep 20, 2019 at 7:31 AM Carin Meier <carinmeier@gmail.com>
> > > wrote:
> > > >
> > > > > Nice!!! Congrats everyone!
> > > > >
> > > > > On Fri, Sep 20, 2019 at 10:28 AM Aaron Markham <
> > > aaron.s.markham@gmail.com>
> > > > > wrote:
> > > > >
> > > > > > Alrighty! The new site is launched. You might need to clear
your
> > > cache.
> > > > > >
> > > > > > Cheers,
> > > > > > Aaron
> > > > > >
> > > > > > On Thu, Sep 19, 2019 at 3:33 PM Aaron Markham <
> > > aaron.s.markham@gmail.com
> > > > > >
> > > > > > wrote:
> > > > > > >
> > > > > > > Thanks everyone. The PRs passed CI, but please continue
holding
> > > off on
> > > > > > > docs and CI edits. Unless there are any objections, I'd
like to
> > > launch
> > > > > > > the new website today.
> > > > > > >
> > > > > > > On Wed, Sep 18, 2019 at 7:46 AM Aaron Markham <
> > > > > aaron.s.markham@gmail.com>
> > > > > > wrote:
> > > > > > > >
> > > > > > > > Hi everyone,
> > > > > > > > The last two PRs [1][2] for the new website and docs
have
> > passed
> > > CI
> > > > > > > > (finally). Please do not make changes to /docs or
/ci until
> we
> > > get
> > > > > > > > these approved and merged. Every time there's a merge
> conflict
> > > it has
> > > > > > > > set us back a day or two while shepherding the PRs
through CI
> > > again.
> > > > > > > > Unless there are catastrophic issues discovered in
a review,
> I
> > > > > > > > recommend that we hold any patches or updates to the
PRs to
> > > follow-up
> > > > > > > > PRs.
> > > > > > > >
> > > > > > > > There are four steps to launch:
> > > > > > > > 1. Once the PRs are approved, the plan is to merge
15885 to
> > > delete
> > > > > the
> > > > > > > > old content first.
> > > > > > > > 2. Then immediately merge 15883 to add in the new
CI flows
> and
> > > > > updates
> > > > > > > > to the content Thomas and I have already had merged
in 15884
> > [3].
> > > > > > > > 3. I will change the website validation Jenkins pipeline
to
> > > point to
> > > > > > > > the new pipeline.
> > > > > > > > 4. I will change the website publishing Jenkins pipeline
to
> > > point to
> > > > > > > > its new pipeline as well. Once triggered, the old
site will
> be
> > > > > > > > replaced with the new one.
> > > > > > > >
> > > > > > > > Post launch we'll need to update the DNS for beta.mxnet.io
> to
> > > point
> > > > > to
> > > > > > > > production, and there will likely be some redirect/.htaccess
> > > updates
> > > > > > > > needed next week to assist with any deep linking and
404
> issues
> > > that
> > > > > > > > pop up.
> > > > > > > >
> > > > > > > > Cheers,
> > > > > > > > Aaron
> > > > > > > >
> > > > > > > > [1] https://github.com/apache/incubator-mxnet/pull/15885
> > > > > > > > [2] https://github.com/apache/incubator-mxnet/pull/15883
> > > > > > > > [3] https://github.com/apache/incubator-mxnet/pull/15884
> > > > > >
> > > > >
> > > >
> > >
> >
> >
> > --
> > *Chaitanya Prakash Bapat*
> > *+1 (973) 953-6299*
> >
> > [image: https://www.linkedin.com//in/chaibapat25]
> > <https://github.com/ChaiBapchya>[image:
> https://www.facebook.com/chaibapat
> > ]
> > <https://www.facebook.com/chaibapchya>[image:
> > https://twitter.com/ChaiBapchya] <https://twitter.com/ChaiBapchya
> >[image:
> > https://www.linkedin.com//in/chaibapat25]
> > <https://www.linkedin.com//in/chaibapchya/>
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message