search

soft-matter / trackpy-examples

sample images, examples, and speed tests for trackpy
Other
21 stars 42 forks source link

Edit for doc #14

Closed danielballan closed 9 years ago

danielballan commented 9 years ago

Updated notebooks along with documentation overhaul in soft-matter/trackpy#180

tacaswell commented 9 years ago

sigh, I really wish gh would play nice with ipython notebooks..

nkeim commented 9 years ago

The revised notebooks are in the new v4 format; they are unreadable by the latest stable version of IPython (2.3.1), which I am using. I'm thinking we should find a way to publish in the v3 format for the time being.

danielballan commented 9 years ago

I definitely agree. The v4 upgrade was not intentional. The latest commit reverts all notebooks for v3.

I manually demoted header tags such that only notebook titles were h1's. I meant to demote h2's to h3's (and so on) but it looks like I missed a few. So to be clear that was my error, not a problem with the rst conversion. Do you like the general flow out the tutorial TOC, once the header tags are uniformly demoted?

nkeim commented 9 years ago

Got it! They all work now, except custom-feature-detection, which is still v4.

I hadn't seen the table of contents. The organization makes sense and is very helpful. I think I would like to demote "Theoretical performance diagnostics: performance_report()" in the prediction notebook. I'll get around to it if you don't.

Thanks, Nathan

On Dec 10, 2014, at 8:52 AM, Dan Allan notifications@github.com wrote:

I definitely agree. The v4 upgrade was not intentional. The latest commit reverts all notebooks for v3.

I manually demoted header tags such that only notebook titles were h1's. I meant to demote h2's to h3's (and so on) but it looks like I missed a few. So to be clear that was my error, not a problem with the rst conversion. Do you like the general flow out the tutorial TOC, once the header tags are uniformly demoted?

— Reply to this email directly or view it on GitHub.

danielballan commented 9 years ago

Fixed. I tested in the build on latest stable IPython -- should be all set now. Let me know. Time to update the links in the README?

nkeim commented 9 years ago

Builds on my [hopelessly outdated] installation as well. I see no reason to wait further.

On Dec 10, 2014, at 12:15 PM, Dan Allan notifications@github.com wrote:

Fixed. I tested in the build on latest stable IPython -- should be all set now. Let me know. Time to update the links in the README?

— Reply to this email directly or view it on GitHub.

nkeim commented 9 years ago

It might be good to refer to the citation instructions on the front page. Perhaps as one of the topics listed under "Documentation." Right now it's not obvious where one would find it. But that can wait if you want to go ahead and merge.

nkeim commented 9 years ago

One more question: Is there a way for users to access the docs, for, say, the latest stable version? It's nice that this is built into readthedocs.

danielballan commented 9 years ago

Good point about the citation. The latest commit on doc-overhaul adds a table with the DOI and Zenodo link for each release. See the README which links directly the relevant section of the introduction page.

There is currently no way for users to access documentation for older versions. There are so many issues with the old docs --- including badly formatted docstrings and other things that would be hard to fix retroactively --- that I think documenting them is not the best place to invest our time. But if you or anyone wants to look into that, of course I support it.

My suggestion would be to figure out sphinx versioning right before the 0.3 release and support versioned documentation henceforth. I know mpl has a good solution for this which we can emulate.

danielballan commented 9 years ago

I will merge the changes to trackpy-notebooks here, with @nkeim's blessing above, but I will wait to merge the doc-overhaul branch on trackpy, pending this discussion on citation and versioning.

nkeim commented 9 years ago

Good point. If you go back in our history far enough to find a major disagreement with the current docs, that's not a version anyone would want to use. But we shouldn't forget this when it's time to release v0.3. Would you mind if I added a note to the release instructions so we don't forget? I could also add a milestone for that release.

danielballan commented 9 years ago

OK. I added a note to the checklist. I leave it to you to create an issue/milestone.