Restructure user guide TOC and doc flow to support new users #414
Conversation
|
@willingc Sorry it's taken me so long to get to this. I am going to review it right now! |
| @@ -1,55 +1,7 @@ | |||
|
|
|||
| The philosophy and the approach | |||
| =============================== | |||
| The philosophy | |||
There was a problem hiding this comment.
It's silly, but I'd prefer to leave it as "The philosophy and the approach" as it's actually an homage to a foundational work that we read in my class, and since that class inspired nbgrader, it's my own little way of recognizing that :-) This is the paper if you're curious:
http://web.stanford.edu/class/psych209a/ReadingsByDate/01_07/Marr82Philosophy.pdf
There was a problem hiding this comment.
Not silly at all. I love that it's tied to the inspiration. I've always loved those spatial cube rotations too. @jhamrick Have you ever met @geekygirldawn? I think you would find each other's research interesting.
|
This is so awesome. Thank you so much for working on this! I left some comments inline, most are pretty minor. I have two more general comments:
Ugh, it seems like this is due to a recent change in pandoc that interacts poorly with nbconvert's philosophy: jupyter/nbconvert#97 My second comment is regarding the filenames -- the reason why I have the starting with numbers is because the notebooks need to be executed in order or else the examples will not be correct. But I'm realizing it really is a pain to maintain the numbering for all the other files, and I don't want to go down the road of having increasing depths of
And then we can rename them so they don't have prefixes. I'm somewhat more in favor of option 1 -- what do you think? |
|
I will give some thought to the numbering and rtd/nbconvert as well. Perhaps the bigger question is what approach to you think would be easiest for people using nbgrader in their courses. That should be the primary concern and we can iterate through how to get to that. |
|
I would like to go ahead and merge this since I'm worried about starting to run into merge conflicts. But I want to keep working on this and get the docs in a somewhat cleaner state for 0.3.0 which I would like to be able to (hopefully) release somewhat soon. @willingc do you think you could just make the few changes for the things I commented on previously? We don't have to worry about the numbering for now, but for some of the other stuff (e.g. resolving TODOs, making sure everything is in rst, etc.) I think that should be fixed before I merge. |
|
Hey @jhamrick, I'll make the changes and rebase. Happy to help with other docs stuff for 0.3.0 too. Just let me know. Not sure when your SIGCSE talk is, but I have some papers that I pulled down before my keynote next week. If you have any interest, I can dump them into a dropbox folder. |
|
Awesome, thanks! There is definitely a bunch of other docs stuff (most of the issues marked as 0.3.0) but most of it is pretty minor. The biggest thing I want to figure out is actually how to build the docs reliably. Getting them to execute on RTD has turned out to be a pain and typically doesn't work, which sort of leaves two options:
I'm really torn between the two. 1 is nice because it means we have up-to-date docs as of every PR. 2 is way easier for contributors, which is nice, but will invariably lead to out-of-date docs. So I'm not sure which is better :-/ Do you have an intuition as to what would be the better route to take? Edit: note that when I mean "execute the docs" I mean execute the notebooks that are part of the user guide. Other things that are executed (e.g. getting the command line options) will still ideally be done on RTD. |
|
@jhamrick I think I got all the updates and I rebased the PR. Just waiting for Travis to be happy. On the more global issue of docs and notebook re: reliable builds, we've come quite a way since October with the workflow and the process. Jon and I are working the next few days on docs for ipywidgets and we'll be playing around with some new tools for notebooks in Sphinx docs. Ideally we would like simple for users and contributors :D |
| contribute to `nbgrader`, I hope you find this project enhances your teaching | ||
| and learning experiences. | ||
|
|
||
| -- *Jess Hamrick*, UC Berkeley |
|
This looks great, thanks @willingc ! :-) |
[WIP] Restructure user guide TOC and doc flow to support new users
jhamrick
changed the title
|
My pleasure. Education is near and dear to my heart @jhamrick :-) |
This PR addresses issue #392. The user guide will frequently be the first documentation read by those interested in trying out nbgrader. The user guide must explain the project and its use, empower the user to try installing nbgrader, and to guide an instructor toward using nbgrader in a course.
The User Guide table of contents is now broken up into logical subsections of 3-4 items per subsection to improve learning and comprehension for those new to nbgrader. Examples are now titled with the format "Workflow example: Instructor..." or "Workflow example: Student..."
"Philosophy" is modified to be a high level project and benefits overview.
A new section for "Interface highlights" is added to share the user interface gifs that were recently added to the README.
There is a new section "Recommended File Structure" which contains the directory layout previously outlined in "Philosophy".
There is a new section for "Installation" using the information in the existing README.
New major heading of "Managing assigments" and "Grading" are added to the TOC.
There are still some markdown that needs to be converted to rst. Also the use of markdown on subsection titles such as for the Example in "03_generating_assignments.ipynb" is not elegant with Sphinx as configured and is not properly suppressing subtitles in Sphinx TOC for the docs. I will look into why.
@jhamrick Thoughts? Not anchored to anything. Just want more useable docs for those new to using nbgrader. It also will be helpful to new developers for nbgrader, such as undergrad students, to have a solid overview and the info to get the project up and working.