Document the usage of `NoDataError` in it's docstring #4359

HeetVekariya · 2023-12-09T16:43:17Z

Fixes #3901

Changes made in this Pull Request:

Adds the usage of NoDataError in it's docstring.

PR Checklist

Tests?
Docs?
CHANGELOG updated?
Issue raised/referenced?

Developers certificate of origin

I certify that this contribution is covered by the LGPLv2.1+ license as defined in our LICENSE and adheres to the Developer Certificate of Origin.

📚 Documentation preview 📚: https://mdanalysis--4359.org.readthedocs.build/en/4359/

github-actions

Hello there first time contributor! Welcome to the MDAnalysis community! We ask that all contributors abide by our Code of Conduct and that first time contributors introduce themselves on the developer mailing list so we can get to know you. You can learn more about participating here. Please also add yourself to package/AUTHORS as part of this PR.

github-actions · 2023-12-09T16:45:30Z

Linter Bot Results:

Hi @HeetVekariya! Thanks for making this PR. We linted your code and found the following:

There are currently no issues detected! 🎉

codecov · 2023-12-09T16:57:32Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (6179b2b) 93.37% compared to head (5569325) 93.37%.

❗ Current head 5569325 differs from pull request most recent head 9dc19e4. Consider uploading reports for the commit 9dc19e4 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           develop    #4359     +/-   ##
==========================================
  Coverage    93.37%   93.37%             
==========================================
  Files          170      184     +14     
  Lines        22340    23452   +1112     
  Branches      4085     4085             
==========================================
+ Hits         20859    21898   +1039     
- Misses         963     1036     +73     
  Partials       518      518

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

lilyminium

Thanks @HeetVekariya for taking on this issue. Docstrings in MDAnalysis are written to be read in two scenarios:

In the code format you see here, e.g. if someone looks at this file or calls help(NoDataError)
In our rendered documentation.

In order for this docstring to be read nicely in our rendered documentation, it should be written in correct ~~Sphinx~~ (edit: reStructuredText) syntax. You can build the docs yourself by navigating to the package/doc/sphinx folder: cd package/doc/sphinx && make html. Alternatively, we build docs for pull requests that get re-built with each push. You can view those here: https://mdanalysis--4359.org.readthedocs.build/en/4359/documentation_pages/exceptions.html#MDAnalysis.exceptions.NoDataError

As you can see, the current formatting looks a bit odd. Could you please re-format using reStructuredText notation (e.g. using * for bullet points and not indenting unnecessarily?)

Below I'll also comment on content.

package/CHANGELOG

package/MDAnalysis/exceptions.py

HeetVekariya · 2023-12-10T08:18:39Z

I am getting error while using make html

lilyminium · 2023-12-10T10:28:20Z

(Apologies, got cut-off in the middle of review) @HeetVekariya looks like you might need to install the documentation dependencies, something like pip install -e ".[doc]" in the package/ directory should install everything you need to build docs.

HeetVekariya · 2023-12-10T10:30:26Z

The docs generated are not good.

package/MDAnalysis/exceptions.py

HeetVekariya · 2023-12-10T10:54:48Z

(Apologies, got cut-off in the middle of review) @HeetVekariya looks like you might need to install the documentation dependencies, something like pip install -e ".[doc]" in the package/ directory should install everything you need to build docs.

I have successfully run pip install -e ".[doc]"
To run make html, first i have commented this line, as i don't have any static folder.
Then i run make html which gives this error

reading sources... [ 99%] documentation_pages/visualization/streamlines_3D
reading sources... [ 99%] documentation_pages/visualization_modules
reading sources... [100%] index

sphinx-sitemap: No pages generated for sitemap.xml

Traceback (most recent call last):
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/site-packages/sphinx/cmd/build.py", line 298, in build_main
    app.build(args.force_all, args.filenames)
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/site-packages/sphinx/application.py", line 355, in build
    self.builder.build_update()
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 293, in build_update
    self.build(to_build,
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 312, in build
    with logging.pending_warnings():
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/contextlib.py", line 142, in __exit__
    next(self.gen)
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/site-packages/sphinx/util/logging.py", line 222, in pending_warnings
    memhandler.flushTo(logger)
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/site-packages/sphinx/util/logging.py", line 187, in flushTo
    logger.handle(record)
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/logging/__init__.py", line 1634, in handle
    self.callHandlers(record)
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/logging/__init__.py", line 1696, in callHandlers
    hdlr.handle(record)
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/logging/__init__.py", line 964, in handle
    rv = self.filter(record)
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/logging/__init__.py", line 821, in filter
    result = f.filter(record)
  File "/home/heet/anaconda3/envs/mdanalysis-dev/lib/python3.10/site-packages/sphinx/util/logging.py", line 427, in filter
    raise exc
sphinx.errors.SphinxWarning: /home/heet/Work/Development/mdanalysis/package/MDAnalysis/coordinates/FHIAIMS.py:docstring of MDAnalysis.coordinates.base.ProtoReader.timeseries:8:Explicit markup ends without a blank line; unexpected unindent.

Warning, treated as error:
/home/heet/Work/Development/mdanalysis/package/MDAnalysis/coordinates/FHIAIMS.py:docstring of MDAnalysis.coordinates.base.ProtoReader.timeseries:8:Explicit markup ends without a blank line; unexpected unindent.
make: *** [Makefile:42: html] Error 2

lilyminium · 2023-12-11T06:17:38Z

Ah whoops, sorry, the following command might work better for you (in the package/ directory):

sphinx-build --keep-going ./doc/sphinx/source ./doc/html

lilyminium · 2023-12-11T06:21:03Z

It looks like the lack of bullets is actually a bug in the Sphinx theme we're using for our documentation -- for some reason the list items here don't have bullets. I've raised an issue in the appropriate repo and will fix it there: MDAnalysis/mdanalysis-sphinx-theme#82

package/MDAnalysis/exceptions.py

lilyminium · 2023-12-11T06:26:39Z

@HeetVekariya could you please add yourself to AUTHORS as this is your first contribution?

lilyminium · 2023-12-12T01:42:23Z

LGTM -- thank you @HeetVekariya for fixing this long-standing issue! Congratulations on your first commit to MDAnalysis :-)

HeetVekariya · 2023-12-12T03:26:11Z

Thank you @lilyminium for guiding me through my PR.
Thank you MDAnalysis for allowing me to contribute.

document the usage of NoDataError in docstring

c864520

github-actions bot reviewed Dec 9, 2023

View reviewed changes

changelog

513a901

lilyminium requested changes Dec 10, 2023

View reviewed changes

HeetVekariya added 2 commits December 10, 2023 15:42

implement changes

77f1bb7

correction in changelog

b425928

lilyminium reviewed Dec 10, 2023

View reviewed changes

package/MDAnalysis/exceptions.py Outdated Show resolved Hide resolved

correction in syntax

c36df59

lilyminium mentioned this pull request Dec 11, 2023

No bullets in list items MDAnalysis/mdanalysis-sphinx-theme#82

Open

lilyminium reviewed Dec 11, 2023

View reviewed changes

package/MDAnalysis/exceptions.py Outdated Show resolved Hide resolved

HeetVekariya and others added 3 commits December 11, 2023 22:40

Add name to AUTHORS

f7b0bb0

implement changes

5569325

Merge branch 'develop' into fix/no-data-error-documentation

9dc19e4

lilyminium merged commit ad40922 into MDAnalysis:develop Dec 12, 2023
13 of 21 checks passed

HeetVekariya deleted the fix/no-data-error-documentation branch December 16, 2023 12:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document the usage of `NoDataError` in it's docstring #4359

Document the usage of `NoDataError` in it's docstring #4359

HeetVekariya commented Dec 9, 2023 •

edited

Loading

github-actions bot left a comment

github-actions bot commented Dec 9, 2023 •

edited

Loading

codecov bot commented Dec 9, 2023 •

edited

Loading

lilyminium left a comment •

edited

Loading

HeetVekariya commented Dec 10, 2023

lilyminium commented Dec 10, 2023

HeetVekariya commented Dec 10, 2023

HeetVekariya commented Dec 10, 2023

lilyminium commented Dec 11, 2023

lilyminium commented Dec 11, 2023

lilyminium commented Dec 11, 2023

lilyminium commented Dec 12, 2023

HeetVekariya commented Dec 12, 2023

Document the usage of NoDataError in it's docstring #4359

Document the usage of NoDataError in it's docstring #4359

Conversation

HeetVekariya commented Dec 9, 2023 • edited Loading

PR Checklist

Developers certificate of origin

github-actions bot left a comment

Choose a reason for hiding this comment

github-actions bot commented Dec 9, 2023 • edited Loading

Linter Bot Results:

codecov bot commented Dec 9, 2023 • edited Loading

Codecov Report

lilyminium left a comment • edited Loading

Choose a reason for hiding this comment

HeetVekariya commented Dec 10, 2023

lilyminium commented Dec 10, 2023

HeetVekariya commented Dec 10, 2023

HeetVekariya commented Dec 10, 2023

lilyminium commented Dec 11, 2023

lilyminium commented Dec 11, 2023

lilyminium commented Dec 11, 2023

lilyminium commented Dec 12, 2023

HeetVekariya commented Dec 12, 2023

Document the usage of `NoDataError` in it's docstring #4359

Document the usage of `NoDataError` in it's docstring #4359

HeetVekariya commented Dec 9, 2023 •

edited

Loading

github-actions bot commented Dec 9, 2023 •

edited

Loading

codecov bot commented Dec 9, 2023 •

edited

Loading

lilyminium left a comment •

edited

Loading