ehmatthes / intro_programming Goto Github PK
View Code? Open in Web Editor NEWA set of IPython notebooks and learning resources for an Introduction to Programming class, focusing on Python.
License: MIT License
A set of IPython notebooks and learning resources for an Introduction to Programming class, focusing on Python.
License: MIT License
Basic workflow:
This workflow is meant to also show students how collaborative tools such as github work.
Makes it much easier to talk about with students and others. Also makes it easier to track which exercises have been completed.
Please share any feedback on this notebook, particularly any suggestions on how to clarify or improve the installation and setup instructions.
I have my overall system to run python2.7 or python3.3. I have not configured a virtualenv to do this yet.
The readme should be updated with this information.
Python function names, such as my_list.append(item), are written right now in an informal way so as to not put off beginners in the text. So append is just referred to as "the append() function".
This seems good, but it does not show people the general format. Perhaps work in the general format as well, at some point in the discussion of each significant function.
I wouldn't call it a "Issue". I would prefer the term "Wish".
I wish there was a easy way to add translations to intro_programming. But I couldn't find a way to add translations to IPython notebooks.
I'd be willing to make an attempt for a translation to german, but I feel that without support from the library side this will fail as soon as there are updates from the original english course.
As we move into focusing on projects, there will be more notes about OS-specific implementations. It would be good to have these collapsible, so readers only see notes specific to their OS.
When people have to fight their OS to do something, it is good to point out in that OS' section that it is easier on other systems. Encourage new people developing on Windows to consider trying Linux. Not evangelism; just objective "This is how you do it on Linux, which is easier for this reason. You might want to give it a try." Follow that with a link to an expanded section in the programming_environment notebook about trying Linux on a vm, or a dual boot, or an extra computer.
It was not clear to me when I started the project that this would be set up as a website. That is one of the primary goals of the project at this point, so this renaming simplifies deployment of html files.
I have a series of custom scripts that build the html pages. Might be much more efficient to use an existing templating engine, rather than my own custom script.
Not a pressing problem, because the custom scripts are not that difficult to manage, and I'm not exactly sure what a larger templating engine would bring to the project at this point.
Templating engines to consider, and other relevant information:
Really should choose a Python static site generator:
I have long thought that one of the biggest strengths of introtopython.org is the ability for strong programmers to improve the site as they look it over. Once it reaches a critical mass, introtopython.org should stay pretty up-to-date and relevant because anyone can catch a mistake, or something out of date, and submit a PR to fix it.
One significant way to grow the project would be to recruit people with expertise in different areas of Python to write notebooks that feature different projects. There could be a whole series of mapping projects, data visualization projects, game projects...
Rather than me or a few people trying to write up a bunch of projects that are not really in our area of expertise, we should try to find the right people to write a series of projects. I think I might reach out to the matpotlib/ data viz community and see if anyone is interested in writing up a project.
In the meantime, if anyone has a specific project to request, let's ticket it and use the Project Request label.
I like Bootstrap sites, and I think it would add something to the project as it stands. We could leave bootstrap at some point, but it would make the styling better than what we see from a simple nbconvert.
Currently you have to go back to the index page or the syllabus to get from one notebook to another. Make a "previous - index - next" style navigation at the top and bottom of each notebook.
One of the strengths of this project is that students can learn a new Python concept, and then apply what they've learned by trying to complete a short series of exercises. That makes high-quality exercises one of the most important parts of the project.
There should be enough exercises that students can get help on a number of exercises, and then still have enough to complete a number of exercises independently. If students don't get to the point of writing simple programs independently, they will not get far in programming.
This could be one of the most straightforward and helpful ways to contribute to the project. If you'd like to help write some exercises or challenges, please fork the project and make a pull request. If you're not sure how to do that, please feel free to ask, and I'll help you get through the first pull request.
An exercise asks the learner to use what was just covered, in a way that mostly repeats the examples that were just given. The exercise can use a new context, but it should tell the learner to use a specific skill to complete a specific task.
A challenge asks the learner to combine what they have just learned with significant previous concepts. A challenge may be less directive and more open to interpretation; it may ask the learner to solve a problem that can be solved with a newly learned concept, without being overly directive about how to use the new concept.
The following notebooks have decent starter exercises for each main topic that is introduced:
These are just some starter exercises, so please feel free to add more.
The following notebooks have sections with no exercises yet:
I would love to have some help writing decent exercises for these notebooks.
Writing exercises and challenges can be fun and satisfying. If you want to help but are not sure how to get started, please introduce yourself in this thread and I'll be happy to help you get started!
As the notebooks gain more detail, I wonder if it might be useful to allow hiding of notes that refer to Python 2. They need to be in there, but it would be good to aim for the simplest, cleanest page possible for learners, without omitting needed details.
(Watching the Python 2/ Python 3 transition difficulties is not fun atm.)
The exercises are one of the strongest features of this project. Most problem sites are aimed at higher-level programmers. When this project is mature, there should be a good set of gradually-graded exercises and challenges that people completely new to programming can work through at their own pace. There should be enough redundancy that people can get help with three or four exercises, and still have three or four more to work through independently.
It is good to have the exercises listed in with the content. It encourages people to try their hand at exercises as they learn, rather than pretending they get something because they read it. It would be quite useful, however, to also have a page that only lists exercises. So, I am envisioning:
The navigation bar is getting crowded:
I added the "Home" element because I couldn't figure out how to make the project name "Introduction to Python" link to the index page. If this can be fixed, we can probably get rid of the "Home" link. Before getting rid of this, we should make sure the new navigation works on mobile.
I'm also not sure about the social media buttons. I'm not sure we need all three there.
Two pages have the "next"-Page link only at the top but not at the bottom.
http://introtopython.org/introducing_functions.html
http://introtopython.org/lists_tuples.html
The other pages are okay.
It is really helpful to see the general syntax before getting into examples and details. If this is not shown, students have to infer the general syntax.
I started this as a series of shell scripts, so that different sections of the pages could be managed separately. But as I look at the whole series, it probably makes sense to pull them into one file, or a smaller series.
May also rewrite the entire series in Python, this was just what I already knew how to do in bash. I will rethink that as I start to play with the html files more. As of right now they are just a mirror of what nbconvert produces.
Regardless, the script should continue to work either by itself, or run from a commit hook.
This is a thread for critiquing the notebook Lists and Tuples. It is under notebooks/lists_tuples.
There should be enough exercises that students can get help on a number of exercises, and then still have enough to complete a number of exercises independently. If students don't get to the point of writing simple programs independently, they will not get far in programming.
This can easily clutter up the notebooks. I have several thoughts about managing this:
There are many collections of Python exercises, and programming exercises in general online. But many of those very quickly get into intermediate-level problems. The problem set that introtopython.org contains could be very appealing to brand-new programmers, who cannot progress quickly enough to keep up with many existing sets of exercises.
The goal of this work is to pull out all exercises and challenges into one place, so that people can choose to try these exercises and challenges without having to skim through all the explanatory text. With a proper presentation, people who get stuck on certain exercises would then be likely to go to the relevant sections of the overall project to learn what they need to in order to complete the exercises. It could be a really good teaching and learning resource, and a good PR piece as well.
I am actively working on this on the branch all_exercise_page. I won't link to the page from the main project until it is complete and presented well, but the evolving page will be at introtopython.org/all_exercises_challenges.html.
I'm not expecting any particular help at this point, but with a few more eyes on the project I'm going to be more clear about my current focus. After landing this, I will probably go back to focusing on having enough content to bring people all the way from hello_world to the projects. Then it will be a fun job of writing up a few projects, and asking some new programmers to try the site out and share feedback. Long-term, there's some fun outreach we can do to teachers who don't come from a CS background, but who want to introduce their students to programming.
The readme is pretty sparse right now, so if you are trying to get involved and have any questions about setup, please feel free to ask them here.
This information is pretty dense for new programmers. The fun part is learning a little bit, and then doing some exercises or trying some challenges. Rather than sprinkle exercises after every little section, encourage people to read a bit and then look at the exercises sections, doing the ones they can.
For "naming and defining a list" on List and Tuples, there is no number for the input, e.g. In[]:.
(very minor)
Functions:
The scripts for converting from ipynb to html successfully depend on a specific formatting for Exercises and Challenges. In particular, the script that builds the all exercises and challenges page needs specific formatting.
This should probably be documented in the readme, or in a page linked to from readme. Research the conventions for supporting readme pages; more markdown pages, or make a wiki? I lean towards markdown, but not sure if that's conventional. I like markdown pages because they are part of the repo that gets cloned.
Exercise sections should follow this format:
This is what the code in your notebook should look like:
<a name='exercises_section_identifier'></a>Exercises
---
#### Title of Exercise
- specific directive
- more specific directive
#### <a name='exercise_title_of_exercise'></a>Title of Exercise
- specific directive
- more specific directive
[new cell]
[top](#)
The script for all_exercises_challenges looks for the top
cell when scraping for exercises and challenges.
Sets of Challenges follow the same format, with the word 'Challenges' in place of 'Exercises'.
Main resources to include:
I have no idea if this is necessary. Technically, I don't think it is. All of the content on the site is actually part of the repository, so I believe the MIT license covers everything.
Still, it would be good to verify whether a CC license is necessary or not.
This will have a number of benefits:
From #29:
The total size of css files included at this point is almost 500kb. On modern systems this should be trivial, especially once resources are cached. But a simple improvement would be to scrape the built pages, and remove any elements from the raw style definitions that are not actually used in html pages.
My rough guess, for the record, is that this step would result in an overall css cumulative file size of 10% of the non-optimized total. There is so much functionality in ipython's css, and bootstrap's css, that the majority of it is unused.
Not a high priority right now, but if the site sees more use this is worth keeping in mind. If you want to see the individual files, take a look at the source for a typical deployed page.
Some of the notebooks, as currently laid out, are pretty long. This makes the project feel more like a reference than an active learning tool. Breaking into smaller sections would probably make it easier for students and teachers to navigate, and to feel like they are making progress.
What's an ideal chunk size?
The Visualizing Global Earthquake Activity has always been well-received. Someone recently requested an extension of this project that would show how to deal with more dimensions of data:
What about displaying 3D data. Any examples? For example, showing roads with the third dimension representing the traffic load on the road or the number of potholes/deaths/accidents per mile.
I would love to get to this at some point, but I probably won't dig into it for a while. This would be a great project for someone to write up.
Individual lines of code can now be highlighted in code cells, once converted to html. This feature will improve the following notebooks:
Now that the project uses matplotlib, and two virtualenvs with two different versions of Python, the setup process can easily fail to complete. There are many dependencies between these packages, and I haven't even brought Basemap into the readme yet.
I have been destroying and building virtualenvs repeatedly, but it would be good to run through the process described in the readme on a vanilla Ubuntu 12.04 vm, and make sure I haven't left out any system-wide requirements.
I would also love to see a version of these setup instructions for non-Ubuntu systems.
I am using the different heading levels inconsistently. This could be cleaned up by clarifying the levels within each notebook.
Something like this is ideal:
ipython nbconvert
dumps all css for all possible notebooks into the head of each html file. This makes sense, because many notebooks are meant to be standalone pieces. For this project, it makes sense to pull the css into a separate file. I believe user's browsers are not caching css, since it is included in each page.
ipython nbconvert --template basic
. This would require generating our own css, but that might work better. I am guessing there is a lot of css that we are not using. It might be reasonable to write our own css rules or create our own template for a basic Introduction to Python site.
@ehmatthes
I am wondering if you have considered an in-browser editor like Skulpt [1]. This will be useful for students to test code live.
I have attached a screenshot for the same. This is a crude hack. I included example code after generating html.
There should be enough exercises that students can get help on a number of exercises, and then still have enough to complete a number of exercises independently. If students don't get to the point of writing simple programs independently, they will not get far in programming.
This can easily clutter up the notebooks. I have several thoughts about managing this:
Initially, notebooks are written with a table of contents, and then a series of text and code cells. Add links from table of contents to appropriate sections in the notebook.
This is a thread for critiquing the notebook Introducing Functions. It is under notebooks/introducing_functions.
If you have some general feedback about the project, feel free to leave it here.
As I have written different sections over the last few months, I have bounced around between the pronouns I, we, and you. This probably reads inconsistently for anyone who works through the notebooks from hello_world through the projects.
As more people start to contribute to the project, I am guessing that "we" is a good approach.
So, I think the following needs to be done:
This is a thread for critiquing the notebook Variables, Strings, and Numbers. It is under notebooks/var_string_num.
For example, when the list.insert(i, item) is introduced, link to the official documentation for insert().
May be good to somehow distinguish between internal and external links.
My main focus is on the static html project at introtopython.org, but I still want the notebooks themselves to work together as a cohesive project, as viewed through Notebook Viewer.
I just updated the index.ipynb notebook to match the index.html page, but this should be checked periodically as the overall project continues to evolve.
I was browsing the site and noticed that on double-digit input history references were a bit closer to the execution than their single digit friends.
From var_string_num.html:
If you remove width: 11ex
from nbconvert_styles.css.
This also ensures that if you have any longer-digit numbers, the padding will be correct still.
I don't think there will be a whole lot of tests for this project, because it's mostly a writing project. I don't envision all of the code in the notebooks being tested; a good error reporting system should take care of those issues.
One test I do care about is the ability to test all links in the project. Links are particularly important for this project, because every time someone follows a link, they are trying to understand something. Broken links make it difficult to build understanding, which would quickly lead to frustration. People also use links to navigate to the topics they are currently working on, and to go back to topics they are starting to understand but need some review on.
This test should:
The test currently finds all links in a local cache of html files. It then tests those links against either a locally served version of the project, or an externally deployed version. The --root (-r) flag lets you set the url root that the files are served at, which is by default http://localhost:8000
, the address of the SimpleHTTPServer that is run by the script itself. The test should either find links from local html files, and then test those locally, or find links from deployed files, and then test those deployed files.
For now, I can use the script as is to test locally (that will continue to work), or I can deploy and then test the deployed files. It's a bit scrappy for the moment, but it works for now and refinement of this script is fairly low-hanging fruit.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.