Run Sphinx checks on MXNet CI

[Anirudh Acharya <an...@gmail.com>]

Hi,

Recently there was a barrage of issues related to documentation that was
raised here -
https://github.com/apache/incubator-mxnet/issues/created_by/aaronmarkham
All the issues are related to Sphinx errors and warnings. These errors
often lead to broken documentation. Ideally such errors should be caught
before a PR gets merged, on the CI.

Since we use Sphinx to generate the documentation for MXNet, can we have
the CI run Sphinx tests on every PR so that we can preempt the problem of
broken documentation.

Any thoughts from the community? What might be involved to make this change
to the CI?


Regards
Anirudh Acharya

Re: Run Sphinx checks on MXNet CI

[Anirudh Acharya <an...@gmail.com>]

Thanks for the reply Aaron. Once the existing Sphinx errors are fixed and
codebase is cleaned up, lets definitely revisit this and try to add a
Sphinx build into the CI pipeline so that we can prevent MXNet
documentation from breaking.

Thanks
Anirudh

On Thu, Nov 8, 2018 at 5:16 PM Aaron Markham <aa...@gmail.com>
wrote:

> Hi Anirudh,
>
> Once the existing errors in docs building are cleaned up, I'm all for
> having CI bubble up a build break when docs are broken by a PR. That
> way we're keeping things up to date and not letting a minor bug turn
> into a serious issue for the entire API documentation. One break
> causes a ripple effect that can go unnoticed and then trying to find
> it is like a needle in a haystack when there are already thousands of
> warnings or errors that are being ignored.
>
> We now have several docs troubleshooting tips in a documentation guide
> thanks to the contributions of @frankfliu, @Roshrini, @vandanavk,
> @vdantu, @vrakesh, and @zachgk.
>
> This documentation guide is published on the developer cwiki:
> https://cwiki.apache.org/confluence/display/MXNET/Documentation+Guide
>
> I plan to continue to add to this guide as more PRs come in that
> exhibit new ways of handling errors or warnings. That way, creating
> docs and troubleshooting any build issues will be much easier.
>
> Please let me know if you have any questions or feedback. You can
> always add that directly to the wiki too.
>
> Cheers,
> Aaron
>
>
> On Thu, Nov 8, 2018 at 11:21 AM Anirudh Acharya <an...@gmail.com>
> wrote:
> >
> > Hi,
> >
> > Recently there was a barrage of issues related to documentation that was
> > raised here -
> > https://github.com/apache/incubator-mxnet/issues/created_by/aaronmarkham
> > All the issues are related to Sphinx errors and warnings. These errors
> > often lead to broken documentation. Ideally such errors should be caught
> > before a PR gets merged, on the CI.
> >
> > Since we use Sphinx to generate the documentation for MXNet, can we have
> > the CI run Sphinx tests on every PR so that we can preempt the problem of
> > broken documentation.
> >
> > Any thoughts from the community? What might be involved to make this
> change
> > to the CI?
> >
> >
> > Regards
> > Anirudh Acharya
>

Re: Run Sphinx checks on MXNet CI

[Aaron Markham <aa...@gmail.com>]

Hi Anirudh,

Once the existing errors in docs building are cleaned up, I'm all for
having CI bubble up a build break when docs are broken by a PR. That
way we're keeping things up to date and not letting a minor bug turn
into a serious issue for the entire API documentation. One break
causes a ripple effect that can go unnoticed and then trying to find
it is like a needle in a haystack when there are already thousands of
warnings or errors that are being ignored.

We now have several docs troubleshooting tips in a documentation guide
thanks to the contributions of @frankfliu, @Roshrini, @vandanavk,
@vdantu, @vrakesh, and @zachgk.

This documentation guide is published on the developer cwiki:
https://cwiki.apache.org/confluence/display/MXNET/Documentation+Guide

I plan to continue to add to this guide as more PRs come in that
exhibit new ways of handling errors or warnings. That way, creating
docs and troubleshooting any build issues will be much easier.

Please let me know if you have any questions or feedback. You can
always add that directly to the wiki too.

Cheers,
Aaron


On Thu, Nov 8, 2018 at 11:21 AM Anirudh Acharya <an...@gmail.com> wrote:
>
> Hi,
>
> Recently there was a barrage of issues related to documentation that was
> raised here -
> https://github.com/apache/incubator-mxnet/issues/created_by/aaronmarkham
> All the issues are related to Sphinx errors and warnings. These errors
> often lead to broken documentation. Ideally such errors should be caught
> before a PR gets merged, on the CI.
>
> Since we use Sphinx to generate the documentation for MXNet, can we have
> the CI run Sphinx tests on every PR so that we can preempt the problem of
> broken documentation.
>
> Any thoughts from the community? What might be involved to make this change
> to the CI?
>
>
> Regards
> Anirudh Acharya