[DOC] doctest MEGA-issue

[hmacdope]

Expected behavior

All the code in our docstring examples should be self-contained and run on its own. They should:

• import the correct modules
• demonstrate the desired behaviour
• run correctly

Actual behavior

A lot of the examples in our docs do not run correctly as they are missing imports, steps, some code logic or all of the above.

By my initial count there are ~350 failing examples and only a handful that work.

We would love this to be fixed! This is a great opportunity for community members and budding open source contributors to get involved as there are lots of docstrings to tackle.

Luckily there is a way to test which doc examples are failing programatically!

1. Navigate to the /package/doc/sphinx directory
2. run make doctest

This will indicate which doc examples are failing.

If you want to tackle multiple doc changes at once editing your makefile command on L130 to include --keep-going will allow you to see the full set of errors.

eg

#L130
	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest --keep-going

Please contribute your changes in a new PR!

If you are new to making PRs and github in general, try our handy contributing guide! Feel free to ping our team if unsure. :)

[richardjgowers]

Another idea would be to add the doctest in the CI and allow it to fail for now, then once we're passing make it another row in the CI.

[sahilempire]

Hey maintainers, I want to work on this issue but I don't have enough knowledge, so can you please assign me and guide me through it?

[hmacdope]

Hi @sahilempire sorry for the slow response. To address this issue you will need to run doctests that is navigate to package/doc/sphinx and run make doctest.

This will show you a bunch of failing doctests which we would like to fix up. Submit a PR fixing one or more! See our contributing guide for more info.

[chrispfae]

Hi, I would also like to work on this issue. @sahilempire Have you already resolved some of the errors? Maybe we can split the work as there are a lot of failing examples?

[sahilempire]

@chrispfae I haven't done anything in this yet and if you want to do something then you can do it.

[IAlibay]

The point of this issue is that there are lots of things that need addressing and so it is assumed that folks might only tackle a smaller section of the failures. Please do raise PRs with fixes - we generally go on a "first PR basis", but we do appreciate it if folks want to coordinate so as to not duplicate efforts.

[nadeem-git-coder]

Hello @hmacdope , I would like to contribute on this issue . Please assign me and guide throughout period.