Opened 7 years ago

Closed 7 years ago

Last modified 7 years ago

#8322 closed task (implemented)

stem examples

Reported by: gsathya Owned by: atagar
Priority: Medium Milestone:
Component: Core Tor/Stem Version:
Severity: Keywords: website
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

Create a /examples or a /contrib dir to host sample scripts or point to code that uses stem. Thoughts?

Child Tickets

Change History (11)

comment:1 Changed 7 years ago by atagar

Status: newneeds_information

Thoughts are that I've been working on the tutorials for the last week and that's my main focus for this weekend. :P

I generally favor tutorials over an /examples directory because it mixes both an explanation about *how* the library should be used with running code. Is there a compelling reason that you'd favor example scripts instead?

comment:2 in reply to:  1 Changed 7 years ago by gsathya

Replying to atagar:

Thoughts are that I've been working on the tutorials for the last week and that's my main focus for this weekend. :P

Aha. Nice!

I generally favor tutorials over an /examples directory because it mixes both an explanation about *how* the library should be used with running code. Is there a compelling reason that you'd favor example scripts instead?

I don't really know how to create a tutorial. I have sample scripts that I've written for metrics foo or other stuff that use stem and I'd like to put up the code snippets somewhere so that others can easily find it. If there should be some sort of an explanation for the code, I can add comments to the code, but I'm not sure I want to spend time figuring out how to use sphinx.

comment:3 Changed 7 years ago by atagar

Gotcha. On reflection I like the idea of our tutorial ending with a list of links to other code that uses stem. One condition though - I want it to be good code, well commented and reviewed. ;)

Would you mind adding the links to this ticket so we can discuss them? It would also be nice to have a 1-2 sentence summary of what each does for the tutorial page.

comment:4 in reply to:  3 Changed 7 years ago by gsathya

Replying to atagar:

Gotcha. On reflection I like the idea of our tutorial ending with a list of links to other code that uses stem. One condition though - I want it to be good code, well commented and reviewed. ;)

Cool :)

Would you mind adding the links to this ticket so we can discuss them? It would also be nice to have a 1-2 sentence summary of what each does for the tutorial page.

For starters - https://pastee.org/2xupy

comment:5 Changed 7 years ago by atagar

For starters - https://pastee.org/2xupy

That's interesting. I was expecting gitweb urls or something else more static. I actually think that I might use this in the general descriptor tutorial if you don't mind (it's a very neat little script). For the examples section though I think that we'll want to use production code.

comment:6 in reply to:  5 Changed 7 years ago by gsathya

Replying to atagar:

For starters - https://pastee.org/2xupy

That's interesting. I was expecting gitweb urls or something else more static.

gitweb url's aren't really static, unless you want to point to the repos themselves. I was thinking of pointing to a particular code sample would be more useful than just saying "xxx uses stem. go search for the place where stem is being used in it's repo".

In case we point to a particular line of code in a gitweb repo, then it wouldn't really be "static", since the code changes so much. This is partly why I wanted an /examples dir.

I actually think that I might use this in the general descriptor tutorial if you don't mind (it's a very neat little script).

Sure :)

For the examples section though I think that we'll want to use production code.

What is "production" code? Do /user/* repos count? Are there any apps that use stem in production? Does metrics-tasks count? Some of the metrics tasks were made when parts of stem's metrics-lib wasn't finished. I don't think there's enough motivation to go and refactor those metrics-tasks since we probably won't run those tasks again.

comment:7 Changed 7 years ago by atagar

gitweb url's aren't really static, unless you want to point to the repos themselves

I was thinking of scripts or projects that make heavy use of it (like arm will). For instance, the former might include things like...

https://gitweb.torproject.org/atagar/tor-utils.git/blob/HEAD:/consensusTracker.py

Though I'll definitely need to clean the script up. Some of the metrics tasks that you've written would also be good candidates.

In case we point to a particular line of code in a gitweb repo, then it wouldn't really be "static", since the code changes so much.

Most projects, and especially small scripts, don't change overly quickly.

What is "production" code? Do /user/* repos count?

I'm not trying to make any hard and fast rules, I just don't like the idea of linking to pastebin dumps. :)

comment:8 in reply to:  7 Changed 7 years ago by gsathya

Replying to atagar:

gitweb url's aren't really static, unless you want to point to the repos themselves

I was thinking of scripts or projects that make heavy use of it (like arm will). For instance, the former might include things like...

https://gitweb.torproject.org/atagar/tor-utils.git/blob/HEAD:/consensusTracker.py

Though I'll definitely need to clean the script up. Some of the metrics tasks that you've written would also be good candidates.

Cool :) #6232, #1854 and #7241 use stem.

What is "production" code? Do /user/* repos count?

I'm not trying to make any hard and fast rules, I just don't like the idea of linking to pastebin dumps. :)

Gotcha :) I find such scripts helpful though. I'm just going to dump them in my $HOME/tormisc for now I guess.

comment:9 Changed 7 years ago by atagar

Keywords: website added

comment:10 Changed 7 years ago by atagar

Resolution: implemented
Status: needs_informationclosed

I've added an examples section to our site...

https://stem.torproject.org/tutorial/double_double_toil_and_trouble.html
https://gitweb.torproject.org/stem.git/commitdiff/4d89032ba6f7d1c2babd54c593668c8e74b23f98

If anyone has additional scripts or applications that use stem then please file separate tickets with both...

  • a summary for the table
  • the gitweb/github/whatever link for the code

Note that I'll *only* add things that are under source control somewhere. Not pastebin links nor trac attachments. ;)

Cheers! -Damian

comment:11 in reply to:  10 Changed 7 years ago by gsathya

Replying to atagar:

I've added an examples section to our site...

https://stem.torproject.org/tutorial/double_double_toil_and_trouble.html
https://gitweb.torproject.org/stem.git/commitdiff/4d89032ba6f7d1c2babd54c593668c8e74b23f98

Great!

If anyone has additional scripts or applications that use stem then please file separate tickets with both...

I think it would be better to discuss and stick everything to one ticket.

  • a summary for the table
  • the gitweb/github/whatever link for the code

Note that I'll *only* add things that are under source control somewhere. Not pastebin links nor trac attachments. ;)

Ok.

Note: See TracTickets for help on using tickets.