Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve DynamicTable documentation #639

Merged
merged 3 commits into from
Jul 6, 2021
Merged

Improve DynamicTable documentation #639

merged 3 commits into from
Jul 6, 2021

Conversation

rly
Copy link
Contributor

@rly rly commented Jul 6, 2021

Motivation

Added a new tutorial on DynamicTable and renamed the old one to be a "how-to guide", inspired by the Divio documentation system: https://documentation.divio.com/

A tutorial should be learning-oriented. The point is to get the user started learning by doing, not serve as a manual or reference. It should focus on concrete steps, not abstract concepts. And it should provide the minimum necessary explanation. Other details can be provided in a how-to guide or reference.

Also added documentation on the options for DynamicTable.get and DynamicTable.to_dataframe.

ref: #579 (comment)

Checklist

  • Did you update CHANGELOG.md with your changes?
  • Have you checked our Contributing document?
  • Have you ensured the PR clearly describes the problem and the solution?
  • Is your contribution compliant with our coding style? This can be checked running flake8 from the source directory.
  • Have you checked to ensure that there aren't other open Pull Requests for the same change?
  • Have you included the relevant issue number using "Fix #XXX" notation where XXX is the issue number? By including "Fix #XXX" you allow GitHub to close issue #XXX when the PR is merged.

@rly rly requested a review from oruebel July 6, 2021 22:04
@rly rly changed the title Update CHANGELOG.md Improve DynamicTable documentation Jul 6, 2021
Comment on lines 644 to 646
# You can also get rows from a :py:class:`~hdmf.common.table.DynamicTable` as a list of
# lists where the i-th nested list contains the values for the i-th row. This method is
# generally not recommended.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would change this to ".. note::" instead since you are not recommending this behavior. It would also be useful to indicate briefly why this is not recommended.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done. Thanks.

@rly rly merged commit e310831 into rc/3.0.0 Jul 6, 2021
@rly rly deleted the enh/dt_tutorial branch July 6, 2021 23:12
rly added a commit that referenced this pull request Jul 6, 2021
rly added a commit that referenced this pull request Jul 6, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants