Opened 5 years ago

Closed 5 years ago

Last modified 3 years ago

#17265 closed enhancement (fixed)

Add info on making tutorials from worksheets

Reported by: kcrisman Owned by:
Priority: minor Milestone: sage-6.4
Component: documentation Keywords:
Cc: Merged in:
Authors: sarah-marie belcastro, Karl-Dieter Crisman Reviewers: Jeroen Demeyer
Report Upstream: N/A Work issues:
Branch: 39f7f9b (Commits) Commit:
Dependencies: #17307, #17308, #17369 Stopgaps:

Description (last modified by jdemeyer)

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.

Change History (36)

comment:1 Changed 5 years ago by kcrisman

  • Branch set to u/kcrisman/makethemtuts
  • Commit set to 4efe05c2ceaf52622c3cda19381c500c540dfd38
  • Status changed from new to needs_review

New commits:

b9800ceUpdate/clarify prereqs for development
61c5519Reorganize and clarify Xcode download situation
b379237More reorganization of developer guide
4efe05cAdd how to create a tutorial from a worksheet

comment:2 Changed 5 years ago by git

  • Commit changed from 4efe05c2ceaf52622c3cda19381c500c540dfd38 to d01885d6250984d4aa095248dd7c83a993ab7085

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

d01885dAdd small detail about how to make linking work right

comment:3 Changed 5 years ago by kcrisman

  • Branch changed from u/kcrisman/makethemtuts to u/kcrisman/mthtuts
  • Commit changed from d01885d6250984d4aa095248dd7c83a993ab7085 to 4363a97bdfd62575c35d59453e8de0f5afb99aa4

New commits:

baaedc9Small fixes to installation manual
08e1359A little more structure to installation guide
e930ee4More reorganization of developer guide
f0e87cdAdd how to create a tutorial from a worksheet
4363a97Add small detail about how to make linking work right

comment:4 follow-up: Changed 5 years ago by jdemeyer

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

comment:5 in reply to: ↑ 4 ; follow-up: Changed 5 years ago by 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.

comment:6 in reply to: ↑ 5 Changed 5 years ago by 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...

comment:7 Changed 5 years ago by jdemeyer

  • Branch changed from u/kcrisman/mthtuts to u/jdemeyer/ticket/17265
  • Created changed from 10/31/14 01:29:21 to 10/31/14 01:29:21
  • Modified changed from 11/05/14 16:10:46 to 11/05/14 16:10:46

comment:8 Changed 5 years ago by jdemeyer

  • Commit changed from 4363a97bdfd62575c35d59453e8de0f5afb99aa4 to 250aee2b7a33b592880c1b199d4f1d4c863acc21
  • Reviewers set to Jeroen Demeyer

New commits:

250aee2Reorder index

comment:9 follow-up: Changed 5 years ago by 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.

comment:10 in reply to: ↑ 9 Changed 5 years ago by 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.

comment:11 Changed 5 years ago by jdemeyer

  • Status changed from needs_review to needs_work

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.

comment:12 Changed 5 years ago by jdemeyer

  • Dependencies set to #17307

comment:13 Changed 5 years ago by jdemeyer

  • Description modified (diff)
  • Summary changed from Add info on making tutorials to Add info on making tutorials from worksheets

comment:14 Changed 5 years ago by git

  • Commit changed from 250aee2b7a33b592880c1b199d4f1d4c863acc21 to 5258c87ad3f3e025cd1019cc8380d813bc5165de

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

a9e9911More reorganization of developer guide
da96745Merge branch 'ticket/17307' into ticket/17265
5258c87Unindent assumptions

comment:15 Changed 5 years ago by jdemeyer

  • Dependencies changed from #17307 to #17307, #17308
  • Status changed from needs_work to needs_review

comment:16 Changed 5 years ago by 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.

comment:17 Changed 5 years ago by git

  • Commit changed from 5258c87ad3f3e025cd1019cc8380d813bc5165de to a412ebdf5d3c5fb36ee7ff7dc3ec34bd8f8d7d26

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

a412ebdDocument --sh instead of -sh command line arguments

comment:18 Changed 5 years ago by 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.

comment:19 Changed 5 years ago by 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.

comment:20 Changed 5 years ago by kcrisman

  • Branch changed from u/jdemeyer/ticket/17265 to u/kcrisman/mthtuts
  • Commit changed from a412ebdf5d3c5fb36ee7ff7dc3ec34bd8f8d7d26 to 98670c40d9982a35d200cd2d9ac427c93820ebec

New commits:

1946fb9Merge branch 'develop' into makethemtuts
98670c4Slightly elaborate on sws2rst instructions

comment:21 follow-up: Changed 5 years ago by kcrisman

  • Dependencies #17307, #17308 deleted

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.

comment:22 in reply to: ↑ 21 Changed 5 years ago by 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.

comment:23 Changed 5 years ago by kcrisman

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

comment:24 Changed 5 years ago by jdemeyer

Yes, I need to explicitly test these instructions.

comment:25 Changed 5 years ago by kcrisman

Okay.

comment:26 Changed 5 years ago by jdemeyer

  • Branch changed from u/kcrisman/mthtuts to u/jdemeyer/ticket/17265
  • Modified changed from 11/14/14 18:18:06 to 11/14/14 18:18:06

comment:27 Changed 5 years ago by jdemeyer

  • Dependencies set to #17307, #17308

comment:28 Changed 5 years ago by jdemeyer

  • Commit changed from 98670c40d9982a35d200cd2d9ac427c93820ebec to f4a5fd39484f020cfdb1c85b6d4ed4b8527da66c

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:

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

comment:29 Changed 5 years ago by jdemeyer

  • Dependencies changed from #17307, #17308 to #17307, #17308, #17369

comment:30 Changed 5 years ago by git

  • Commit changed from f4a5fd39484f020cfdb1c85b6d4ed4b8527da66c to 39f7f9b951f4f65cf7d867196b052d7cebcecea9

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

39f7f9bSmall changes to the documentation documentation

comment:31 Changed 5 years ago by 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"!

comment:32 Changed 5 years ago by jdemeyer

  • Status changed from needs_review to positive_review

comment:33 Changed 5 years ago by kcrisman

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

comment:34 Changed 5 years ago by vbraun

  • Branch changed from u/jdemeyer/ticket/17265 to 39f7f9b951f4f65cf7d867196b052d7cebcecea9
  • Resolution set to fixed
  • Status changed from positive_review to closed

comment:35 Changed 3 years ago by chapoton

  • Authors changed from sarah-marie belcastro, Karl-Dieter Crisman to Sarah-Marie Belcastro, Karl-Dieter Crisman
  • Commit 39f7f9b951f4f65cf7d867196b052d7cebcecea9 deleted

comment:36 Changed 3 years ago by kcrisman

  • Authors changed from Sarah-Marie Belcastro, Karl-Dieter Crisman to sarah-marie belcastro, Karl-Dieter Crisman
Note: See TracTickets for help on using tickets.