More user-friendly docs (Addressing Issue #1175) by richardjgowers · Pull Request #1190 · MDAnalysis/mdanalysis

richardjgowers · 2017-01-26T22:01:38Z

Docs split into User guide, then API reference

Changes made in this Pull Request:

PR Checklist

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

richardjgowers · 2017-01-26T22:05:44Z

So Issue #1175 seemed to get warmly received, so I've started an implementation of it.

I tried to come up with topics that covers everything to a moderate level, if anyone can think of more topics or a better way to order topics, then this is the PR for that!

orbeckst · 2017-01-28T23:14:18Z

That's a good structure. Now we just need some content... Should we essentially merge this as an incomplete PR and then raise Issues/PRs for things that are still incomplete? Or make PRs against this branch? In any case, I think it would be good to have sub-issues to encourage splitting the load.

jbarnoud · 2017-01-29T09:25:11Z

I would advocate against merging the PR as it, even to be filled latter on. This would break the develop branch, which we try to avoid as much as possible.

richardjgowers · 2017-01-31T11:55:01Z

We can PR onto this branch, then merge this when everything is done I guess

orbeckst · 2017-02-23T09:58:56Z

package/doc/sphinx/source/documentation_pages/bonds_angles_torsions.rst

+::
+
+     for segment in u.segments:
+	 segment.atoms.guess_bonds()


identation seems wrong

no it's correct on that line. 4 spaces it aligns as it should.

orbeckst · 2017-02-23T10:01:08Z

package/doc/sphinx/source/documentation_pages/advanced_reader.rst

@@ -0,0 +1,7 @@
+.. -*- coding: utf-8 -*-
+
+.. All the advanced options in Reader usage and creation


Also MemoryReader

kain88-de · 2017-03-28T07:58:52Z

package/doc/sphinx/source/documentation_pages/coordinate_manipulation.rst

+     >>> vel = ag.velocities
+     NoDataError: Timestep does not contain velocities
+
+These properties return a **copy** of the data for the AtomGroup at the


Do really return a copy of the arrays? That seems wasteful and slow in terms of system memory. I thought it was a reference that is returned.

I think we use fancy slicing on ts._pos so yes, it will be a copy.

jbarnoud · 2017-03-28T08:00:25Z

It cannot be a reference: it is a non contiguous slice of the overall array.

…

On 03/28/2017 09:58 AM, Max Linke wrote: ***@***.**** commented on this pull request. ------------------------------------------------------------------------ In package/doc/sphinx/source/documentation_pages/coordinate_manipulation.rst <#1190 (comment)>: > +properties will always be available from the AtomGroup, however if the loaded +trajectory does not have this data then a ``NoDataError`` will be raised. + +:: + + >>> import MDAnalysis as mda + >>> from MDAnalysisTests.datafiles import PSF, DCD + >>> ag = u.select_atoms('name CA') + >>> ag.positions + array([[ 11.66462231, 8.39347267, -8.98323059], + [ 11.41483879, 5.43442154, -6.51348448], + ... + >>> vel = ag.velocities + NoDataError: Timestep does not contain velocities + +These properties return a **copy** of the data for the AtomGroup at the Do really return a copy of the arrays? That seems wasteful and slow in terms of system memory. I thought it was a reference that is returned. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1190 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABUWupVGZ0PQdnNnDPUsSU2d0MGEn9cOks5rqL29gaJpZM4LvMeQ>.

richardjgowers · 2017-03-28T08:06:06Z

Yeah a numpy fancy index is always a copy, afaik we can't return a reference/view On Tue, 28 Mar 2017, 9:00 a.m. Jonathan Barnoud, <notifications@github.com> wrote:

…

It cannot be a reference: it is a non contiguous slice of the overall array. On 03/28/2017 09:58 AM, Max Linke wrote: > > ***@***.**** commented on this pull request. > > ------------------------------------------------------------------------ > > In > package/doc/sphinx/source/documentation_pages/coordinate_manipulation.rst > < #1190 (comment)>: > > > +properties will always be available from the AtomGroup, however if the loaded > +trajectory does not have this data then a ``NoDataError`` will be raised. > + > +:: > + > + >>> import MDAnalysis as mda > + >>> from MDAnalysisTests.datafiles import PSF, DCD > + >>> ag = u.select_atoms('name CA') > + >>> ag.positions > + array([[ 11.66462231, 8.39347267, -8.98323059], > + [ 11.41483879, 5.43442154, -6.51348448], > + ... > + >>> vel = ag.velocities > + NoDataError: Timestep does not contain velocities > + > +These properties return a **copy** of the data for the AtomGroup at the > > Do really return a copy of the arrays? That seems wasteful and slow in > terms of system memory. I thought it was a reference that is returned. > > — > You are receiving this because you commented. > Reply to this email directly, view it on GitHub > < #1190 (review)>, > or mute the thread > < https://github.com/notifications/unsubscribe-auth/ABUWupVGZ0PQdnNnDPUsSU2d0MGEn9cOks5rqL29gaJpZM4LvMeQ >. > — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#1190 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AI0jB9Bk0CI3FoKnKuK5qa_nNo48PctGks5rqL4ZgaJpZM4LvMeQ> .

orbeckst · 2017-05-10T00:39:48Z

@richardjgowers is this PR something we want to get into 0.16.x or should we re-target to 0.17.0?

richardjgowers · 2017-05-10T09:58:14Z

@orbeckst ideally it gets merged as soon as its finished. This isn't code breaking/making so I don't think we're bound by version numbers.

orbeckst · 2017-05-19T18:18:56Z

package/doc/sphinx/source/index.rst

+
+
+API Reference
+=============


With the sidebar navigation in #1126 I am pretty sure that we need a single toctree. I would suggest to keep the top-toctree pretty light, essentially

Overview

User guide

API Reference

References

where User guide is what you called "MDAnalysis Basics"

orbeckst

Let's rebase after #1126 has been merged and see if the docs are acceptable. Then we can add it to 0.16.1; otherwise we keep working on it and put it into the next release.

Docs split into User guide, then API reference: outlining the general structure of the docs.

- bonds angles and torsions section of docs - Added rst docs for bonds angles torsions - Updated topologyobjects docstrings - Update advanced_reader.rst - Update advanced_universe.rst

orbeckst · 2017-05-25T00:21:54Z

I am currently rebasing to develop and cleaning up the history. I will force-push to this branch.

orbeckst · 2017-06-16T04:47:40Z

I moved it to 0.17.0 – I don't think that anyone has currently got the bandwidth to make this happen for 0.16.2.

orbeckst · 2017-09-12T17:15:11Z

I moved it to 1.0.

Obviously, any improvements to the docs are more than welcome at any time, but this should not hold up a 0.17.

orbeckst · 2020-01-18T23:12:45Z

Will the completion of the UserGuide by @lilyminium make this PR obsolete?

I think we still want to clean up the user docs and make them more API centric and have the UserGuide as the explanatory document – opinions?

lilyminium · 2020-01-19T22:54:57Z

@orbeckst As part of GSOD I was hoping to clean up the API docs as well, yes. I'm keeping an ongoing list of more significant doc issues in #2401

richardjgowers · 2020-03-10T11:49:41Z

I think this is obsolete thanks to @lilyminium

richardjgowers added the Component-Docs label Jan 26, 2017

richardjgowers added this to the 0.16.0 milestone Jan 26, 2017

orbeckst changed the title ~~Addressing Issue #1175~~ More user-friendly docs (Addressing Issue #1175) Jan 28, 2017

orbeckst added the Work in progress label Jan 28, 2017

orbeckst reviewed Feb 23, 2017

View reviewed changes

richardjgowers mentioned this pull request Mar 15, 2017

Introduce operators to groups #1239

Merged

4 tasks

kain88-de reviewed Mar 28, 2017

View reviewed changes

orbeckst modified the milestones: 0.16.0, 0.16.x Apr 7, 2017

orbeckst reviewed May 19, 2017

View reviewed changes

richardjgowers added 4 commits May 24, 2017 17:18

more user friendly docs (Issue #1175)

f404181

Docs split into User guide, then API reference: outlining the general structure of the docs.

new topology and advanced usage docs

dfae2df

- bonds angles and torsions section of docs - Added rst docs for bonds angles torsions - Updated topologyobjects docstrings - Update advanced_reader.rst - Update advanced_universe.rst

Coordinate manipulation docs

b7edbf1

Outline of working with AtomGroups

1d14297

fixed missing headings so that sphinx builds without errors

c5d6d6c

orbeckst force-pushed the issue-1175-doc_restructure branch from 85ee177 to c5d6d6c Compare May 25, 2017 00:35

orbeckst added this to the 0.17.0 milestone Jun 16, 2017

orbeckst removed this from the 0.16.x milestone Jun 16, 2017

orbeckst modified the milestones: 1.0, 0.17.0 Sep 12, 2017

lilyminium mentioned this pull request Jun 24, 2019

Separate class docstrings and __init__ docstrings in API #2282

Closed

richardjgowers closed this Mar 10, 2020

RMeli deleted the issue-1175-doc_restructure branch December 23, 2023 21:57

		@@ -0,0 +1,7 @@
		.. -- coding: utf-8 --

		.. All the advanced options in Reader usage and creation

Conversation

richardjgowers commented Jan 26, 2017

Changes made in this Pull Request:

PR Checklist

Uh oh!

richardjgowers commented Jan 26, 2017

Uh oh!

orbeckst commented Jan 28, 2017

Uh oh!

jbarnoud commented Jan 29, 2017

Uh oh!

richardjgowers commented Jan 31, 2017

Uh oh!

orbeckst Feb 23, 2017

Choose a reason for hiding this comment

Uh oh!

kain88-de Feb 23, 2017

Choose a reason for hiding this comment

Uh oh!

orbeckst Feb 23, 2017

Choose a reason for hiding this comment

Uh oh!

kain88-de Mar 28, 2017

Choose a reason for hiding this comment

Uh oh!

orbeckst May 10, 2017

Choose a reason for hiding this comment

Uh oh!

jbarnoud commented Mar 28, 2017 via email

Uh oh!

richardjgowers commented Mar 28, 2017 via email

Uh oh!

orbeckst commented May 10, 2017

Uh oh!

richardjgowers commented May 10, 2017

Uh oh!

orbeckst May 19, 2017

Choose a reason for hiding this comment

Uh oh!

orbeckst left a comment

Choose a reason for hiding this comment

Uh oh!

orbeckst commented May 25, 2017

Uh oh!

orbeckst commented Jun 16, 2017

Uh oh!

orbeckst commented Sep 12, 2017

Uh oh!

orbeckst commented Jan 18, 2020

Uh oh!

lilyminium commented Jan 19, 2020

Uh oh!

richardjgowers commented Mar 10, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants