Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adds Notebook Learning Guide, Resolves #311 #313

Open
wants to merge 8 commits into
base: master
from

Conversation

Projects
None yet
4 participants
@ianmilligan1
Copy link
Member

commented Jul 4, 2019

GitHub issue(s):

#311

What does this Pull Request do?

This adds a new learning guide: "Getting Started with the Archives Unleashed Cloud Jupyter Notebooks," written by Sarah McTavish.

In addition, this PR:

  • Adds a link to the learning guide from the derivatives landing page;
  • Adds links to it to complement the blog post written by Ryan Deschamps; and
  • Adds a test for it.

How should this be tested?

TravisCI should turn green.

More importantly, others should give this a read and make sure it properly addresses how to install the Notebooks. I'll take the lead on updating the text and can chat with Sarah as needed.

Interested parties

@ruebot @SamFritz

@ianmilligan1 ianmilligan1 requested review from ruebot and SamFritz Jul 4, 2019

@ruebot

This comment has been minimized.

Copy link
Member

commented Jul 4, 2019

@codecov-io

This comment has been minimized.

Copy link

commented Jul 4, 2019

Codecov Report

Merging #313 into master will increase coverage by 0.06%.
The diff coverage is 100%.

Impacted file tree graph

@@            Coverage Diff            @@
##           master    #313      +/-   ##
=========================================
+ Coverage   89.33%   89.4%   +0.06%     
=========================================
  Files          35      35              
  Lines         619     623       +4     
=========================================
+ Hits          553     557       +4     
  Misses         66      66
Impacted Files Coverage Δ
test/controllers/pages_controller_test.rb 100% <100%> (ø) ⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 563e34f...9e96ddd. Read the comment docs.

@ianmilligan1 ianmilligan1 changed the title Adds Notebook Learning Guide Adds Notebook Learning Guide, Resolves #311 Jul 4, 2019

@ruebot
Copy link
Member

left a comment

Couple of small tweaks. There is also a few instances of double spaces after a full stop. . should find them all.

</div>
<br />
<h3 class="about_h3" id="1toc">Introduction</h3>
<p class="about_p">The Archives Unleashed Cloud Notebooks require the use of Anaconda Distribution’s Jupyter Notebooks, as well as a working knowledge of the command line. For an introduction to the command line, see Ian Milligan and James Baker’s <%= link_to('Introduction to the Bash Command Line', 'https://programminghistorian.org/en/lessons/intro-to-bash', target: '_blank') %>.</p>

This comment has been minimized.

Copy link
@ruebot

ruebot Jul 4, 2019

Member

The Archives Unleashed Cloud Notebooks require the use of the Anaconda Distribution.

Also:

<p class="about_p">For more information on what each notebook can do, see Ryan Deschamps’s <%= link_to('"Exploring Web Archival Data through Archives Unleashed Cloud Jupyter Notebook."', 'https://news.archivesunleashed.org/exploring-web-archival-data-through-archives-unleashed-cloud-jupyter-notebooks-7605c6ca2b33', target: '_blank') %></p>
<p class="about_p">Notebooks contain code and visualizations like the following one from <strong>auk-notebook-network</strong>:</p>
<%= image_tag("Notebook-04.png", alt: "The Jupyter Notebook Network example.", class:"body_img")%>
<p class="about_p">In order to use each notebook, click on the notebook from the directory list — the notebook will open in a new tab or window. Each notebook has been pre-loaded with sample data from the B.C. Teachers' Labor Dispute (2014) collection from the University of Victoria Libraries. This data is great to play with in order to learn how the tools work! Once you are ready to load your own data, there are a few extra steps to load it into the notebooks.</p>

This comment has been minimized.

Copy link
@ruebot

ruebot Jul 4, 2019

Member

Link to Archive-It collection.

@SamFritz
Copy link
Member

left a comment

Great tutorial! Content was easy to follow, layout was clean (really like the use of helper boxes for extra info). Just have a few suggestions.

<br />
<h3 class="about_h3" id="1toc">Introduction</h3>
<p class="about_p">The <%= link_to('Archives Unleashed Cloud Notebooks', 'https://github.com/archivesunleashed/auk-notebooks', target: '_blank') %> require the use of the <%= link_to('Anaconda Distribution','https://www.anaconda.com/distribution/', target: '_blank') %>, as well as a working knowledge of the command line. For an introduction to the command line, see Ian Milligan and James Baker’s <%= link_to('Introduction to the Bash Command Line', 'https://programminghistorian.org/en/lessons/intro-to-bash', target: '_blank') %>.</p>
<p class="about_p">The Cloud Notebooks also require the use of the Archives Unleashed Cloud and an Archive-It account, in order to run and process Archives Unleashed WARC files. The Archives Unleashed Cloud <%= link_to('documentation', '/documentation', target: '_blank') %> will get you started on creating an account and linking your Archive-It account to the Archives Unleashed Cloud. We will be using the Archives Unleashed Cloud in order to generate the derivatives used with the Cloud Notebooks for text, domain, and network analysis.</p>

This comment has been minimized.

Copy link
@SamFritz

SamFritz Jul 9, 2019

Member

drop "in order"

<h3 class="about_h3" id="1toc">Introduction</h3>
<p class="about_p">The <%= link_to('Archives Unleashed Cloud Notebooks', 'https://github.com/archivesunleashed/auk-notebooks', target: '_blank') %> require the use of the <%= link_to('Anaconda Distribution','https://www.anaconda.com/distribution/', target: '_blank') %>, as well as a working knowledge of the command line. For an introduction to the command line, see Ian Milligan and James Baker’s <%= link_to('Introduction to the Bash Command Line', 'https://programminghistorian.org/en/lessons/intro-to-bash', target: '_blank') %>.</p>
<p class="about_p">The Cloud Notebooks also require the use of the Archives Unleashed Cloud and an Archive-It account, in order to run and process Archives Unleashed WARC files. The Archives Unleashed Cloud <%= link_to('documentation', '/documentation', target: '_blank') %> will get you started on creating an account and linking your Archive-It account to the Archives Unleashed Cloud. We will be using the Archives Unleashed Cloud in order to generate the derivatives used with the Cloud Notebooks for text, domain, and network analysis.</p>
<p class="about_p">This tutorial was originally created to be used with the Mac OS. There are minor differences to running commands on Windows or Linux, as per the <%= link_to('lesson here', 'https://programminghistorian.org/en/lessons/intro-to-bash', target: '_blank') %>. Once the Cloud notebooks have been cloned to your system, the minor operating system differences should disappear!</p>

This comment has been minimized.

Copy link
@SamFritz

SamFritz Jul 9, 2019

Member

suggested change: "This tutorial was originally created to be used with the Mac OS...." -->

"This tutorial was created using a Mac OS. There are minor differences when running commands on Windows or Linux, as per the lesson here."

<p class="top_toc"><%=link_to('Back to Top', anchor: '#toc-top') %></p>

<h3 class="about_h3" id="2toc">Getting Started</h3>
<p class="about_note"><strong>Want to try out the notebooks on sample data?</strong> If so, you can jump right in by launching our notebooks in a <%= link_to('binder environment','https://mybinder.org/v2/gh/archivesunleashed/auk-notebooks/master', target: '_blank') %>. If you want to use your own data, please follow these instructions.</p>

This comment has been minimized.

Copy link
@SamFritz

SamFritz Jul 9, 2019

Member

change "on" to "with"

<p class="top_toc"><%=link_to('Back to Top', anchor: '#toc-top') %></p>

<h3 class="about_h3" id="4toc">Generating the Derivatives</h3>
<p class="about_p">In order to use the Cloud Notebooks with your own data, you will first need to analyze your collection using the Archives Unleashed Cloud, as described in the Cloud <%= link_to('documentation', '/documentation', target: '_blank') %>. This process can take several hours, depending on the queue of jobs running at the time. You will receive an email notification once the analysis is complete.</p>

This comment has been minimized.

Copy link
@SamFritz

SamFritz Jul 9, 2019

Member

suggestion: "depending on the queue of jobs running at the time" --> drop "at the time"

@ianmilligan1

This comment has been minimized.

Copy link
Member Author

commented Jul 9, 2019

Thanks so much for your reviews, @ruebot and @SamFritz. I think it's ready for re-review, and potential merge if it looks good on your end. Happy to make more tweaks as well, of course.

@SamFritz
Copy link
Member

left a comment

Looks good @ianmilligan1!

<p class="about_p">The Cloud Notebooks also require the use of the Archives Unleashed Cloud and an Archive-It account, in order to run and process Archives Unleashed WARC files. The Archives Unleashed Cloud <%= link_to('documentation', '/documentation', target: '_blank') %> will get you started on creating an account and linking your Archive-It account to the Archives Unleashed Cloud. We will be using the Archives Unleashed Cloud in order to generate the derivatives used with the Cloud Notebooks for text, domain, and network analysis.</p>
<p class="about_p">This tutorial was originally created to be used with the Mac OS. There are minor differences to running commands on Windows or Linux, as per the <%= link_to('lesson here', 'https://programminghistorian.org/en/lessons/intro-to-bash', target: '_blank') %>. Once the Cloud notebooks have been cloned to your system, the minor operating system differences should disappear!</p>
<p class="about_p">The Cloud Notebooks also require the use of the Archives Unleashed Cloud and an Archive-It account to run and process Archives Unleashed WARC files. The Archives Unleashed Cloud <%= link_to('documentation', '/documentation', target: '_blank') %> will get you started on creating an account and linking your Archive-It account to the Archives Unleashed Cloud. We will be using the Archives Unleashed Cloud in order to generate the derivatives used with the Cloud Notebooks for text, domain, and network analysis.</p>
<p class="about_p">This tutorial was created with MacOS. There are minor differences when running commands on Windows or Linux, as per the <%= link_to('lesson here', 'https://programminghistorian.org/en/lessons/intro-to-bash', target: '_blank') %>. Once the Cloud notebooks have been cloned to your system, the minor operating system differences should disappear!</p>

This comment has been minimized.

Copy link
@SamFritz

SamFritz Jul 9, 2019

Member

MacOS or macOS? Not sure if there is a standard for this

This comment has been minimized.

Copy link
@ruebot

ruebot Jul 9, 2019

Member

Wikipedia has: macOS.

This comment has been minimized.

Copy link
@ianmilligan1

ianmilligan1 Jul 10, 2019

Author Member

Good catch - updated throughout. Should be good now.

@ruebot

ruebot approved these changes Jul 9, 2019

@ruebot

This comment has been minimized.

Copy link
Member

commented Jul 9, 2019

I can merge one we sort out Sam's comments.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.