I've also got 16 sphinx warnings, which I could look at solving under this PR if preferred to two PRs.

We should skip that doctest, rather than adding it to the default install guide. Dask has many many optional dependencies, ideally our test suite should run clean with only the required ones.

Adding a # doctest: +SKIP comment to the proper lines in that docstring should resolve the issue there.

I've also got 16 sphinx warnings, which I could look at solving under this PR if preferred to two PRs.

Either works, up to you. Thanks for looking into this!

Cool, sounds ideal @jcrist. I'll modify the PR to suit!

ping here

@martindurant apologies for the delay, busy week. Will have a look at this today! :-)

I've updated the sphinx configuration to deal with doctest extension not being loaded. It appears it wasn't available for make doctest to work.

Also there are a fair few doctests failing. I have updated the PR name, can I start fixing some of those perhaps? The original SQL warning has disappeared! :-)

Doctest summary
===============
  943 tests
  292 failures in tests
    0 failures in setup code
    0 failures in cleanup code
build finished with problems.
make: *** [doctest] Error 1

This looks great! Do these run on CI? And if not, do you think they should?

Hi @jsignell

I think eventually they probably should on doc build, but I guess not whilst there are 200+ failing. This might be worth resolving and adding another PR akin to this one for linkcheck you've got, once they're resolved? It kind of follows the same logic you had for the link checker, to be fair: if the test is there always worth running it on release...

It might take me a little while to go through these but I'm willing to have a crack at it (I do like a project.) It's perfect for my exploring the codebase in more depth (which is why I'm focusing on doc related issues currently...)

However, I defer to more experienced dask contributors such as yourself to make that call: just my two cents worth! Always happy for more feedback about how best to organise/manage this in line with your expectations too! :-)

I'd say if you are happy going through and fixing up doctests you should go for it! Probably many of them are just missing an import. We can defer deciding about CI until after they are fixed up. Thanks for working on this!

No worries, happy to be involved. Will have a good crack at it this weekend. Thanks!

Noticed that some of the doctest skip flags haven't been stripped on the live docs under this method so will verify that's operating correctly. I forget, but when / how are the documents reproduced on the live system?

I've managed to fix quite a few of the obvious errors up, a few more to go and may well need to add a PR for distributed documentation updates (or just avoid the doctest devling into them!) Need to have a look at the warnings and wotnot as well, so I'll clean up the commits eventually!

Doctest summary
===============
  961 tests
  112 failures in tests
    0 failures in setup code
    0 failures in cleanup code
build finished with problems, 25 warnings.
make: *** [doctest] Error 1

Noticed that some of the doctest skip flags haven't been stripped on the live docs

I don't think that the doctest flags are being stripped at all. Is that something that you expect to be happening?

when / how are the documents reproduced on the live system?

The docs are built on every push to master: https://github.com/dask/dask/blob/master/.github/workflows/ci.yml

We can also merge in a partial docs-only PR if this is getting unwieldy.

Hi @jsignell not to worry for the moment, I'll continue resolving the issues for the moment (it'll be a day or two due to other commitments), but if anything significant comes up I'll consider tactics to ensure there's minimal impact! :-)

With respect to the # doctest: +SKIP removal, I have seen mention that they can be stripped out somewhere, but the sphinx documentation just cast a bit of doubt on that. I'll have a bit more of a dig about, but I assume it'd be quite nice if they didn't appear in the final HTML code block outputs?

Hope my tardiness with concluding this isn't too annoying!

Ok! Yeah, I think it's fine either way on the doctest skip stripping. It'd be nice to not have those strings in the rendered docs but don't worry too much about it. Take your time, this is a really nice cleanup effort.

A touch busy at the moment, but will be more free to work on this post-Tuesday! ;-)

Thank you for the attention to detail here @JimCircadian . I have a preference to not use the .. doctest:: skip bits in order to keep everything at the same indentation level. I find that the indentation is a bit more disruptive than # doctest: +SKIP declarations. Do you have thoughts here? If you feel strongly the other way I'm happy to cede.

Thank you for the attention to detail here @JimCircadian . I have a preference to not use the .. doctest:: skip bits in order to keep everything at the same indentation level. I find that the indentation is a bit more disruptive than # doctest: +SKIP declarations. Do you have thoughts here? If you feel strongly the other way I'm happy to cede.

Hi @mrocklin

That's a great steer, I actually was playing around with blacks auto indentation advice which resulted in that, so going to revert that out and keep it all consistent. 👍

Hoping to have a good crack at this at the tail end of the holiday and see if we can get it out of draft stage.

Many of the last 112 errors are related to autodoc picking up the distributed module and with issues surrounding the wrapping of FFT implementations. I'm digging into that now.

@mrocklin I removed the last commit and am looking at standardising the blocks to always use the comment approach (I had added a few for larger blocks.) I'm a fan of the consistency so will aim for that to be the approach.

Looking at the above problems and the likely solutions I'm hoping to have the PR cleared up for the end of the weekend, but I suspect (from some initial digging) that getting autodoc and doctest to play nicely might be interesting!

Getting there, bit tricky to achieve doctest skips for imported items without considerable changes, so working my way through them

Doctest summary
===============
  937 tests
   67 failures in tests
    0 failures in setup code
    0 failures in cleanup code
build finished with problems, 10 warnings.

This is still WIP, got another chance to look at it over the weekend. Still a bit stumped about how to approach some of the trickier tests that are getting pulled in, but I'll send up a flare in here if I can't figure the solution! ;-)

I've managed to insert the necessary skips or alterations to account for docstrings causing issues. The FFT's were easily taken care of with the skip_docstring method from utils (I knew this would be a good way to explore the codebase!!! 😄 )

There are certainly suboptimal solutions to some of these. Such as coarsen in array/chunk, which I think is being ignored due to ambiguous calls, which can be easily solved. I've also inserted a slightly dirty import for numpy into the global config, though this can likely be done locally if preferable.

Just checking the CI runs, then will leave it open for merge if appropriate! Please let me know what needs improving ;-)

EDIT: Forgot to show off the exciting dcotest output I'd been working towards 🤣

Doctest summary
===============
  803 tests
    0 failures in tests
    0 failures in setup code
    0 failures in cleanup code
build succeeded, 11 warnings.

Testing of doctests in the sources finished, look at the results in build/doctest/output.txt.

The warnings are irritating, a mixture of solveable and Pandas import problems. They don't appear to be blockers in the current form. 🍺

Also, referring back to my mention of stripping out doctest flags, I saw it here, but it should be enabled by default ;-)

Another edit, a load of warnings (they seem to change) but having trouble converging on the test setup of the Travis CI run

Doctest summary
===============
  802 tests
    0 failures in tests
    0 failures in setup code
    0 failures in cleanup code
build succeeded, 26 warnings.

The changes here look sensible to me. @JimCircadian do you think that we should want on handling the warnings, or merge what we have here now?

Hi @mrocklin

Probably worth merging as is I think. Weirdly I've just done another fresh run on my dev laptop and got no warnings (it was a late night on Friday!) I will have a little play with a fresh environment to make sure, but they generally don't seem to indicate anything critical (perhaps reasonably so!)

I'm happy to help with any further work to develop CI based on this if need be, will need to look back over the ticket to see what was discussed!

Doctest summary
===============
  802 tests
    0 failures in tests
    0 failures in setup code
    0 failures in cleanup code
build succeeded.

Testing of doctests in the sources finished, look at the results in build/doctest/output.txt.
Testing of doctests in the sources finished, look at the  results in build/doctest/output.txt.