[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.

[Tanmay-Malviya]

Respected Sir/madam, I am a 1 year experienced programmer, please let me work on this issue.

[chandra20500]

Hi I want to solve this issue. could you please assign this to me

[orbeckst]

To everyone who wants to work on this issue: that's great. But please note that we do not assign issues. Instead you should do the work and submit a PR that references this issue.

Normally, we only look at the first PR for each issue (see our GSOC FAQ Can I claim an issue to work on?) but for this umbrella issue we will look at any PR that addresses non-overlapping fixes.

When you start working on one doc test, check any linked, open PRs so that you only start work on an issue that has not been addressed yet.

[orbeckst]

You can also look at merged linked PRs to see how to do it.

[MohitKumar020291]

Hello maintainers , can you please provide me some resources to read/learn about that issue? It would be very helpful for me as a beginner. Thanks.

[orbeckst]

@MohitKumar020291 see https://docs.python.org/3/library/doctest.html , https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html, and https://github.com/MDAnalysis/mdanalysis/issues/3925#issue-1451364932

[MohitKumar020291]

Hello mentors, I have opened a PR, can anyone please review it? I will be very grateful. Thanks.

[paraglondhe098]

Hello there, Is the issue is fixed ? if not I also want to contribute on it.

[MohitKumar020291]

@paraglondhe098, this issue is not closed.

[orbeckst]

@paraglondhe098 thank you for offering to contribute to the project, that's awesome. Please read through the comments from the top down. This issue just says that we want to add more doc tests. So simply find some code in the docs and make a PR that doc-tests that code. If no-one else has submitted a PR on the same code, we'll have a look at yours.

[man0045]

Hi there , i want to fix this issue can you please assign me this issue

[RMeli]

Hi @man0045, we do not assign issues to people. If there are no open pull requests (PRs) tackling this issue, you can open a PR directly with (some) fixes.

This is tagged as "mega"-issue so we don't expect a PR to fix all of the failing tests. You can start by fixing a few (for example all the ones in the same file, etc.).

[IAlibay]

re-opening as accidentally closed by PR fixing a sub section of this issue.

[HeetVekariya]

• How can i import datafiles in lib folder (package/MDAnalysis/lib)
• There are many import errors like this, which has XYZ_bz2 not defined error, which i think is defined in the MDAnalysisTests folder.
• I tried this from MDAnalysisTests.datafiles import XYZ_bz2 which does not works.
• Also tried this from MDAnalysis.tests.datafiles import XYZ_bz2 which gives ImportError: MDAnalysisTests package not installed

[orbeckst]

import MDAnalysisTests.datafiles as data

u = mda.Universe(data.XYZ_bz2)

For this to work you need to install the MDAnalysisTests package.

[HeetVekariya]

• In this, the error arrises due to hard compare between, Expected: <MDAnalysis.analysis.align.AlignTraj object at ...> and Generated: <MDAnalysis.analysis.align.AlignTraj object at 0x7f4d87e00a00> which can be anything.
• I am thinking to go with isinstance(alignment, AlignTraj) which checks if the instance is present or not.
• Should i go with that or any other way to follow ?

[orbeckst]

Check the doctest documentation. I believe ... can be used as a wildcard.

[HeetVekariya]

Check the doctest documentation. I believe ... can be used as a wildcard.

• You are right, It is applied there rightly but the implementation is wrong, documentation says that ... should be followed by white space.
• So solution can be <MDAnalysis.analysis.align.AlignTraj object at ..., can i proceed with this ?

[HeetVekariya]

I think this issue is closed by mistake.

[RMeli]

@HeetVekariya yes, thank you!

[HeetVekariya]

• currently i am working on cluster.py files doctest error (it contains five errors, from which i have solved 4, but stuck at one). I am not able to solve this error, can you please guide me in this ?

code: cluster.py

Error:

UNEXPECTED EXCEPTION: AttributeError("'ClusterCollection' object has no attribute 'metadata'")
Traceback (most recent call last):
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/doctest.py", line 1350, in __run
    exec(compile(example.source, filename, "single",
  File "<doctest MDAnalysis.analysis.encore.clustering.cluster.cluster[10]>", line 1, in <module>
  File "<doctest MDAnalysis.analysis.encore.clustering.cluster.cluster[10]>", line 1, in <listcomp>
AttributeError: 'ClusterCollection' object has no attribute 'metadata'
/home/heet/Work/Development/mdanalysis/package/MDAnalysis/analysis/encore/clustering/cluster.py:145: UnexpectedException
===================================================== short test summary info =====================================================
FAILED analysis/encore/clustering/cluster.py::MDAnalysis.analysis.encore.clustering.cluster.cluster

[orbeckst]

If you manually follow the example (eg in ipython or Jupyter) do you get the same error, i.e., the object misses the attribute? If yes, then look through the documentation to see if the attribute is documented and ought to exist. If it is documented but not there, raise an issue. If it’s not documented, remove the example.

[HeetVekariya]

• For me it is not possible to run it manually as it gives many internal import error.
• Though i run below code to get the class type:

>>> print([type(cluster) for cluster in cluster_collection][:2])
[<class 'MDAnalysis.analysis.encore.clustering.ClusterCollection.ClusterCollection'>, 
<class 'MDAnalysis.analysis.encore.clustering.ClusterCollection.ClusterCollection'>]

• Documentation says that there are two attributes associated with that class (MDAnalysis.analysis.encore.clustering.ClusterCollection.ClusterCollection) and that are elements and metadata, we can check here.
• According to the docs this code must not give attribute error, but it does(shown below). So what should to be done now to solve it ?

>>> print([cluster.metadata["ensemble_membership"]
...          for cluster in cluster_collection][:2])
[array([1, 1, 1, 1, 2]), array([1, 1, 1, 1, 1])]

AttributeError: 'ClusterCollection' object has no attribute 'metadata'

• I also noticed overflow in the docs here, please confirm if is it also on your side too or i am referring to the old version of the docs.