Add info on making tutorials from worksheets

[kcrisman]

Sage-combinat has been adding tutorials to their own ​website for quite some time. Others should know how to do this more easily from worksheets.

[kcrisman]

New commits:

​b9800ce	Update/clarify prereqs for development
​61c5519	Reorganize and clarify Xcode download situation
​b379237	More reorganization of developer guide
​4efe05c	Add how to create a tutorial from a worksheet

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​d01885d

Add small detail about how to make linking work right

[kcrisman]

New commits:

​baaedc9	Small fixes to installation manual
​08e1359	A little more structure to installation guide
​e930ee4	More reorganization of developer guide
​f0e87cd	Add how to create a tutorial from a worksheet
​4363a97	Add small detail about how to make linking work right

[jdemeyer]

"Advanced Sage Coding Details": I don't like the word "advanced". Perhaps "Further Sage Coding Details"?

[kcrisman]

"Advanced Sage Coding Details": I don't like the word "advanced". Perhaps "Further Sage Coding Details"?

Feel free to come up with a better suggestion, I figured this one wouldn't be very good. I tried about five different ideas before settling on this one as the least bad of them. What I really wanted was "Language-specific coding details that you might not have thought were important but will really bite you if you don't read them, plus some stuff about C libraries", but that seemed a bit too long.

[kcrisman]

"Advanced Sage Coding Details": I don't like the word "advanced". Perhaps "Further Sage Coding Details"?

Feel free to come up with a better suggestion, I figured this one wouldn't be very good.

Just to clarify, I mean "feel free to come up with a better suggestion than mine". I'm not 100% sold on your first try, but I could be...

[jdemeyer]

New commits:

​250aee2

Reorder index

[kcrisman]

Okay, this seems fine and (as expected) doc builds correctly, though I'm surprised you put the manuals earlier. I wish there was a way to indicate that the coding details included how to interface with libraries, but that would be such a long title.

Since you're the reviewer, you can be the one to set the review status, but I'm happy with this.

[kcrisman]

Since you're the reviewer, you can be the one to set the review status, but I'm happy with this.

By which I mean if the only objection you had was that, we're good to go - I didn't know if you had any other questions.

[jdemeyer]

I tried to follow the instructions on how to make a tutorial and they simply don't work for me:

(sage-sh) jdemeyer@tamiyo:tmp$ ls -l Tutorial.sws 
-rw-r--r-- 1 jdemeyer jdemeyer 204897 Nov  8 10:50 Tutorial.sws
(sage-sh) jdemeyer@tamiyo:tmp$ sage --sws2rst Tutorial.sws 
Processing Tutorial.sws
Unable to process file ('Tutorial.sws')
Error message: [Errno 20] Not a directory: '/tmp/Tutorial.sws/sage_worksheet'
Exiting.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​a9e9911	More reorganization of developer guide
​da96745	Merge branch 'ticket/17307' into ticket/17265
​5258c87	Unindent assumptions

[jdemeyer]

I separated the "reorganize the index" part as a new ticket (with positive review!) #17307.

I think the part about using --sws2rst should only be added to the manual if it works properly, see #17308.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​a412ebd

Document --sh instead of -sh command line arguments

[kcrisman]

Your two commits are fine (assuming they look okay built, but I'm not going to check that now). I will think about #17308 and whether that should be a dependency or not over the weekend. On the face of it, I'd rather document what not to do now and have that ticket be separate.

[kcrisman]

They only additional thing I find wrong about this is that I/we need to be more explicit about adding one's file to index.rst.

[kcrisman]

New commits:

​1946fb9	Merge branch 'develop' into makethemtuts
​98670c4	Slightly elaborate on sws2rst instructions

[kcrisman]

To me, the issue of a small bug in sage -sws2rst is nearly orthogonal to adding this information. If you strongly disagree, luckily I have two alternate fixes you can try out for #17308 - let me know.

[jdemeyer]

Replying to kcrisman:

To me, the issue of a small bug in sage -sws2rst is nearly orthogonal to adding this information. If you strongly disagree, luckily I have two alternate fixes you can try out for #17308 - let me know.

I disagree (not strongly). I don't like to add documentation explicitly refering to something which is known to be broken. Let me also add that I didn't intentionally look for bugs in sws2rst. I just tried the instructions, happened to store the .sws file in /tmp and got in trouble. Together with the fact that #17308 likely has an easy fix, I think we should wait for #17308.

[kcrisman]

Anything else to do here now that #17308 is green?

[jdemeyer]

Yes, I need to explicitly test these instructions.

[kcrisman]

Okay.

[jdemeyer]

sphinx-build doesn't work for me:

(sage-sh) jdemeyer@tamiyo:make_tutorial$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Traceback (most recent call last):
  File "/usr/local/src/sage-git/local/bin/sphinx-build", line 5, in <module>
    from pkg_resources import load_entry_point
  File "build/bdist.linux-x86_64/egg/pkg_resources.py", line 2817, in <module>
  File "build/bdist.linux-x86_64/egg/pkg_resources.py", line 451, in _build_master
  File "build/bdist.linux-x86_64/egg/pkg_resources.py", line 464, in _build_from_requirements
  File "build/bdist.linux-x86_64/egg/pkg_resources.py", line 639, in resolve
pkg_resources.DistributionNotFound: Sphinx==1.1.2
make: *** [html] Error 1

I have no idea why the wrong version (1.1.2 vs. 1.2.2) is in that file, reinstalling Sphinx doesn't help.

---

New commits:

​f4a5fd3

Merge remote-tracking branch 'origin/develop' into ticket/17265

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​39f7f9b

Small changes to the documentation documentation

[kcrisman]

Your documentation patch is good. I think this didn't get noticed until the Sphinx upgrade #16396 because we had been using previous betas or versions. Another good reason for those to be in "Merged in"!

[kcrisman]

Sweet, thanks. Hopefully people will actually use this now.

[kcrisman]

See comment:19:ticket:17247