Adds Notebook Learning Guide, Resolves #311 #313

ianmilligan1 · 2019-07-04T11:45:58Z

GitHub issue(s):

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


        Initial check-in of notebooks learning guide


        Adds links to derivative; tests; route config


        Update img resolution, fixes prose, test style fix


        Adding learning guide link to FAQ/docs

Complements the blog post for now

ruebot · 2019-07-04T11:56:28Z

@ianmilligan1 double-check your tests https://travis-ci.org/archivesunleashed/auk/builds/554213847#L396-L399

@ruebot


        Fixing page test (thx @ruebot)

codecov-io · 2019-07-04T12:01:47Z

Codecov Report

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

@@            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.

ruebot

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

ruebot · 2019-07-04T13:40:52Z

app/views/pages/notebooks.html.erb

+    </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>


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

Also:

link: "Archives Unleashed Cloud Notebooks" to https://github.com/archivesunleashed/auk-notebooks

link "Anaconda Distribution" to https://www.anaconda.com/distribution/

ruebot · 2019-07-04T13:40:52Z

app/views/pages/notebooks.html.erb

+    <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>


Link to Archive-It collection.

@ruebot


        Review (thx @ruebot)

SamFritz

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.

SamFritz · 2019-07-09T16:19:20Z

app/views/pages/notebooks.html.erb

+    <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>


drop "in order"

SamFritz · 2019-07-09T16:19:20Z

app/views/pages/notebooks.html.erb

+    <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>


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."

SamFritz · 2019-07-09T16:19:20Z

app/views/pages/notebooks.html.erb

+    <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> 


change "on" to "with"

SamFritz · 2019-07-09T16:19:20Z

app/views/pages/notebooks.html.erb

+    <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>


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

@SamFritz


        Review (thx @SamFritz)

ianmilligan1 · 2019-07-09T20:28:41Z

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

Looks good @ianmilligan1!

SamFritz · 2019-07-09T20:49:15Z

app/views/pages/notebooks.html.erb

-    <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>


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

Wikipedia has: macOS.

Good catch - updated throughout. Should be good now.

ruebot · 2019-07-09T21:37:22Z

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


        MacOS -> macOS

ianmilligan1 added 4 commits Jul 2, 2019

Initial check-in of notebooks learning guide

a1fcdb0

Adds links to derivative; tests; route config

c268027

Update img resolution, fixes prose, test style fix

53cc4fc

Adding learning guide link to FAQ/docs

Loading status checks…

f25aa8c

Complements the blog post for now

ianmilligan1 requested review from ruebot and SamFritz Jul 4, 2019

Fixing page test (thx @ruebot)

Loading status checks…

107247e

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

ruebot requested changes Jul 4, 2019

View changes

Review (thx @ruebot)

Loading status checks…

0140965

SamFritz approved these changes Jul 9, 2019

View changes

Review (thx @SamFritz)

Loading status checks…

fa60f79

SamFritz approved these changes Jul 9, 2019

View changes

ruebot approved these changes Jul 9, 2019

View changes

MacOS -> macOS

Loading status checks…

9e96ddd

ruebot merged commit 1f1d9b0 into master Jul 11, 2019
1 check passed

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

ruebot deleted the issue-311 branch Jul 11, 2019

archivesunleashed/auk

Adds Notebook Learning Guide, Resolves #311 #313

Adds Notebook Learning Guide, Resolves #311 #313

ianmilligan1 commented Jul 4, 2019

This comment has been minimized.

ruebot commented Jul 4, 2019

This comment has been minimized.

codecov-io commented Jul 4, 2019 •

edited

ruebot left a comment

This comment has been minimized.

This comment has been minimized.

SamFritz left a comment

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

ianmilligan1 commented Jul 9, 2019

SamFritz left a comment •

edited

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

ruebot commented Jul 9, 2019

archivesunleashed/auk

Join GitHub today

Adds Notebook Learning Guide, Resolves #311 #313

Conversation

ianmilligan1 commented Jul 4, 2019

What does this Pull Request do?

How should this be tested?

Interested parties

This comment has been minimized.

ruebot commented Jul 4, 2019

This comment has been minimized.

codecov-io commented Jul 4, 2019 • edited

Codecov Report

ruebot left a comment

This comment has been minimized.

This comment has been minimized.

SamFritz left a comment

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

ianmilligan1 commented Jul 9, 2019

SamFritz left a comment • edited

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

ruebot commented Jul 9, 2019

codecov-io commented Jul 4, 2019 •

edited

SamFritz left a comment •

edited