carpentries-incubator / python-packaging-publishing Goto Github PK

add description to packaging episode

in the sphinx documentation episode

add to exercise at the beginning of episode on example gallery

in the sphinx documentation episode

make links to good readmes more direct, expand on components,

add description of where pip pulls from and how it works, to [packaging episode[(https://github.com/brownsarahm/python-data-project/blob/gh-pages/_episodes/03-packaging-installing.md)

pages that use sphinx gallery and are a good example

in virtualenv episode

in virtualenv episode

to the packaging episode

there are rough sketeches of each already, but improvements could be made to any or all of them.

During the pilot lesson at CC@Home2020, participants provided additional link(s) in the etherpad (see line 213) relating to licenses for Python packages. The material could be improved by adding a link out to further resources like this, on licenses, READMEs, contributing guides, citation files (e.g. CFF), issue & PR templates, etc.

From feedback received during pilot lesson at CC@Home2020: the lesson material could be improved by starting with a more authentic project/code, e.g. a relatively simple Numpy analysis. It was suggested that this would be more likely to reflect the experience of the target audience, and could make the value of tools such as virtualenv/a requirements.txt file more immediately apparent later in the lesson.

Hi,

there are some things I'd suggest to improve Ep03:

- Fix the ModuleNotFoundError

If I run the code in the current version of Episode 03, when I run the following line:

from conversions import temperature, speed

Assuming I'm in the conversions/ directory as instructed, I get the following error:

---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
<ipython-input-4-180d6e73763d> in <module>
----> 1 from conversions import temperature, speed

ModuleNotFoundError: No module named 'conversions'

This does work, if I'm in the conversions/ directory:

from temperature import fahr_to_celsius
from speed import kph_to_ms

Not entirely sure if I am doing anything wrong.

If I open a Python terminal from the parent directory of conversions and run import sys; sys.path.append('conversions'), which is explained earlier in the episode, I can run the imports as they are currently displayed (from conversions import temperature, speed).

- Move the Pip section to somewhere else in the Episode

As described in #58, the Pip section seems a bit out of place. I'd suggest moving it somewhere else in the Episode.

I will document other things I find in this issue. May I submit a PR to address these two points in the meantime?

Comment here with your institution and some notes on the audience if you are interested in a pilot run of the material.

The title of the lesson vs my open leaders project. The working title is kind of long, but the title repository title might not be descriptive enough. Discussion on this point is welcome.

Hi,

I would like to work on Episodes 04-conda and 04-virtualenv regarding the use of environments. This includes tackling #18 and #19.

I would suggest either:

• swapping the order of the episodes; or
• merging them together.

Episode 04-virtualenv starts an explanation of why environments matter, but there is 04-conda before that already mentions them. I would argue in favour of presenting VirtualEnv first and then Conda.

Any thoughts?

Thanks,
Vini

Edit: sorry, I did not realize that both episodes were named as "Episode 04". Given this, a merge would make even more sense.

Hi Sarah,
I had a little trouble finding an email address for you, so I hope this will do.
I'm a doctoral candidate in a data science-adjacent field, and I recently have packaged and published the framework that I've been using and developing internally for managing my experimental setups.
it's hosted at: (https://gitlab.com/bjmuld/xanity)

I saw your work with Mozilla in their newsletter and found our interests to be in alignment.
My intention is to simplify and abstract the need to manage the complex tasks of multiple
(conda) environments, output data cataloging, source control, and the like.

If you have time, please have a look and share any feedback you might have.
Congrats on your successes with Mozilla!

-Barry

to the project organization episode

the idea is to start that section off with an activity to explore and discuss organizations before introducing guiding principles.

links txample projects would also help and not only things that are 'good'

LInks to and mention of these type of requires in the project setup section would help motivate why and what factors to consider in organization.

One example:

• NeurIPS: https://github.com/paperswithcode/releasing-research-code

This issue is a place to collect related examples to be added

Several CC@Home2020 participants were keen to learn good practice for where to put results/outputs files (inside or outside 'data' folder?), whether to put them under version control, etc.

The material could be improved by adding discussing this somehwere - maybe episode 1, or maybe later in the lesson if more appropriate. This could include mention of using .gitignore to prevent certain intermediate/results files from being included in the repository e.g. if very large.

The episode on publishing is pretty slim, could use a lot of content add and exercises. This isssue is also to gather references for that effort.

How can the lesson best provide learners with "toy" content to organize?

Is it too much to do a little bit of start from scratch and then some organizing or should it be all one?

Which one?

Ideally a sample of what researchers might have: code in notebooks, maybe some functions, etc to start organising?

I was thinking an example of how imports can change with the init, like, reducing the levels of the imports eg how you can use the package.module once you have init or even package.function() if the depending on the contents of the init file? In pilots of this workshop (and in working with students in research ) they tend to struggle with what to put in the init file, other than pattern matching what's already there.

Originally posted by @brownsarahm in #71 (comment)

connect them together to make the outcomes more clear to help clarify who is qualified.

tie in the application domains

Would it make sense to include the use of the cookie cutter like this one? It generates the file and folder structure for the package.

During the pilot lesson at CC@Home2020, learners were unclear on the meaning of . in the pip install . command. The material could be improved by expanding on this to make the use of a relative path explicit.

The example code to be used in 03-packaging-installing should be more related to scientific computing to be accessible to the target audience.

The second exercise could be improved by expanding on the content/purpose of the files being created. E.g. learners were variously placing new_technique.py in experiments/ (reasoning that this was the code for an experimental, "work in progress" technique) and packageName/ (arguing that this is the code for the novel technique at the core of the package). See the exercise solution for intended destinations of each file.

in the sphinx documentation episode

In the section "Step 1: Creating a directory" of episode 2, the example command is mkdir package-name. Package names with hyphens are invalid so this example should be adjusted, either to packageName or something else e.g. Vehicles (as seems to be intended based on the text immediately above the example code block).

at the end of the episode an exerise that summarized the type sof documentation would be good. There is a skeleton of one in the episode already

in preparation for hacktoberfest

@fmichonneau has updated the lesson template to enable support of Incubator lessons!

This update:

• Creates a top-of-page banner to indicate that this lesson is in the incubator (and not an official Carpentries lesson). This banner is in addition to the existing "lesson life cycle" banner that appears on some official Carpentries lessons (for example the geospatial lessons) to indicate whether lessons are pre-alpha, alpha, beta, or stable.

• Changes the license information to make it clear the copyright is not held by The Carpentries or any of its lesson programs.

• Replaces The Carpentries (or SWC/DC/LC) logo in the upper left hand corner of the template with The Carpentries Incubator logo.

@fmichonneau and I are happy to do the heavy lifting of bringing this template into your lesson repository (or helping you with the logistics if you'd like to try it yourself). Once this has been done, your lesson will appear on a "Community Contributed Lessons" page on The Carpentries website!

Please respond to this issue to let us know if you approve these changes. Please also indicate whether you would prefer to pull in the template update yourself, or would prefer @fmichonneau and I to take the lead on that. Looking forward to posting your lesson publically and getting the word out about this awesome resource!

in packaging episode

The material in episode 2 could be improved by mentioning (maybe in a callout box) pip install -e, which allows the latest version of a module/package under active development to be imported and used without the need to re-install after every set of changes. (See line 351 of the etherpad from CC@Home2020.)

in the sphinx documentation episode

to the project organization episode

The new dependency resolver to be switched on by default in pip 20.3 (October 2020) might affect the material taught in this lesson. I'm opening this issue as a way to flag up the possibility, and perhaps as a place to discuss the implications for this lesson of the impending change to Pip's default behaviour.

From feedback received during the pilot lesson at CC@Home2020: the lesson could be improved by adding, or linking out to instructions for deploying HTML files built with Sphinx. It was suggested that readthedocs could be a good choice for this.

in the sphinx documentation episode

sphinx-quickstart no longer asks about setup for automatic API documentation as part of the set of questions asked during initial setup. The lesson material should be updated to reflect this change and show how the learner can configure sphinx to generate the API docs.

From feedback received during the pilot lesson at CC@Home2020: the lesson could be improved by adding some discussion of Python package terminology and hierarchy: packages, modules, classes, functions, etc.

add outline of the minimum working example for strucutre of a python module in packaging episode

in virtualenv episode

to the project organization episode