Skip to content

JMM 2025 updates #40

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.

Sign up for GitHub

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

Merged
StevenClontz merged 2 commits into from
Jan 6, 2025
Merged

JMM 2025 updates #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4149435
swap chapters
StevenClontz Jan 6, 2025
0173c25
move a few things around
StevenClontz Jan 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 23 additions & 51 deletions source/ch-coding.ptx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@
<section xml:id="sec-codespaces">
<title>Codespaces</title>
<p>
While the quick <c>GitHub.dev</c> interface is great
for quick edits, many projects require the ability
While the quick <c>GitHub.dev</c> interface we used
to get started in <xref ref="ch-first-repo"/> is great
for quick uploads or edits, many projects require the ability
to run applications and execute code as you would on
your personal computer. Fortunately, GitHub offers a
service to run such programs on their servers.
Expand Down Expand Up @@ -240,50 +241,6 @@ Array.from({ length: 10 }, _ => {
<caption>Sample Javascript code</caption>
</listing>
</section>
<section xml:id="sec-github-pages-codespace">
<title>Previewing GitHub Pages</title>
<p>
Another useful application of Codespaces is the ability
to preview your GitHub Pages site created in
<xref ref="sec-using-a-template"/>. Return to that repository
on <c>GitHub.com</c> and create a new Codespace
(<xref ref="note-create-codespace"/>).
</p>
<p>
To spin up your live preview, open a terminal by using the
shortcut noted in <xref ref="remark-terminal-shortcut"/>. To make
sure the necessary software has been installed, type <c>bundle</c>
and hit <kbd>Enter</kbd>. Then, you can enter <c>jekyll serve</c>
to start the preview server.
</p>
<p>
You'll see some output, and eventually
<c>Server address: http://127.0.0.1:4000</c>. At that time an
alert will appear that says <q>Your application on port 4000
is available</q>. You can use its <q>Open in browser</q> button,
or hover over the <c>http://127.0.0.1:4000</c> link to be given
the same option.
</p>
<p>
This should open a URL such as
<c>random-words-123randomletters789-4000.app.github.dev</c>,
which will show a live preview of your GitHub Pages site in a new
tab. As soon as you make edits in your Codespace tab, you can
return to this tab to (within a second or two) see how your edits
will update your live site. Note that this URL is private to you,
and your public site won't be updated until you Commit &amp; Sync
your changes
(<xref ref="note-commit-sync"/>).
</p>
<p>
Personally, I use <c>GitHub.dev</c> (or even just the
<c>GitHub.com</c> edit button) rather than a full
Codespace when adding a quick post or making a quick edit on
many of my GitHub Pages websites. But the Codespace option is very
handy for when bigger changes are necessary, and you want to make
sure everything looks just right before pushing it live to the public.
</p>
</section>
<section xml:id="sec-codespace-management">
<title>Managing Your Codespaces</title>
<p>
Expand All @@ -297,9 +254,9 @@ there is the option to pay for additional resources.
As a mathematician
who almost exclusively uses GitHub Codespaces for doing the kinds
of work described in this handbook (and does so for much longer
periods of time than a tpyical mathematician),
periods of time than a typical mathematician),
I've only surpassed GitHub's free quota on the rare occassion
(and when I do, I've paid only \$2-\$6 per month).
(and when I do, I've paid only <m>\$2</m>-<m>\$6</m> per month).
I accomplish this by halting
my Codespaces when I'm not actively working on them.
</p>
Expand Down Expand Up @@ -343,9 +300,11 @@ Here is what these environments look like.
<section xml:id="sec-powering-up-your-codespce">
<title>Powering up your Codespce</title>
<p>
By default, your codespace will use a
2-core processor, 8GB of RAM, and 32GB of storage, with a quota of
40 usage hours per month. This is fine for many tasks,
As of January 2025, a default codespace will use a
2-core processor and 8GB of RAM, with a quota of
60 usage hours and 15GB storage per month. (This is increased
to 90 usage hours and 20GB storage for Pro/Education users.)
This is fine for many tasks,
but if you're doing data analysis (<xref ref="ch-jupyter"/>) or
formalized mathematics (<xref ref="sec-lean"/>) you may want some
more resources at your disposal.
Expand Down Expand Up @@ -374,5 +333,18 @@ the virtual machine that should be provisioned when creating a Codespace,
allowing for the automatic installation of appropriate software/libraries/dependencies
necessary for the use of a given repository.
</p>
<remark>
<p>
Setting up a custom <c>.devcontainer</c> is a slick way to
ensure you and your collaborators/students are running exactly
the same software (including versions, dependencies, etc.)!
No more <q>It works on my machine</q> while <q>I can't get it
to work on my machine</q>!
</p>
<p>
See <url href="https://code.visualstudio.com/docs/devcontainers/create-dev-container#_create-a-devcontainerjson-file">VisualStudio.com/docs/devcontainers</url>
to learn more.
</p>
</remark>
</section>
</chapter>
11 changes: 11 additions & 0 deletions source/ch-first-repo.ptx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,4 +227,15 @@ on each commit to see exactly what has changed from the previous commit across
all files.
</p>
</section>
<section>
<title>Next steps</title>
<p>
Now that you've gotten the hang of the basics of
committing and pushing changes to a repository,
you can move on to using Codespaces to write
and execute programs and code (<xref ref="ch-coding"/>)
or setting up a webpage hosted by GitHub
(<xref ref="ch-github-pages"/>).
</p>
</section>
</chapter>
50 changes: 47 additions & 3 deletions source/ch-website.ptx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ without using HTML.)
</p>
<p>
Use <c>GitHub.dev</c> (<xref ref="opening-github-dev"/>)
to create three files in the root of your project.
to create three files in the root of a new or existing repository.
<ul>
<li>
<p>
Expand Down Expand Up @@ -243,8 +243,8 @@ edits. After a while (<xref ref="actions-progress" />) you should
be able to refresh your website and see your updated title, name, etc.
(In <xref ref="sec-github-pages-codespace"/>, we will learn how to
preview our edits more quickly, and without needing to push them to a
live website, but at the expense of a more complicated
editing environment.) You can repeat this process after each of the
live website, provided we're comfortable using a Codespace as explored in
<xref ref="ch-coding"/>.) You can repeat this process after each of the
edits described below to see your results reflected on the live website.
</p>
</subsection>
Expand Down Expand Up @@ -338,4 +338,48 @@ tags:
</listing>
</subsection>
</section>
<section xml:id="sec-github-pages-codespace">
<title>Previewing GitHub Pages</title>
<p>
Another useful application of Codespaces is the ability
to preview your GitHub Pages site created in
<xref ref="sec-using-a-template"/>. Return to that repository
on <c>GitHub.com</c> and create a new Codespace
(<xref ref="note-create-codespace"/>).
</p>
<p>
To spin up your live preview, open a terminal by using the
shortcut noted in <xref ref="remark-terminal-shortcut"/>. To make
sure the necessary software has been installed, type <c>bundle</c>
and hit <kbd>Enter</kbd>. Then, you can enter <c>jekyll serve</c>
to start the preview server.
</p>
<p>
You'll see some output, and eventually
<c>Server address: http://127.0.0.1:4000</c>. At that time an
alert will appear that says <q>Your application on port 4000
is available</q>. You can use its <q>Open in browser</q> button,
or hover over the <c>http://127.0.0.1:4000</c> link to be given
the same option.
</p>
<p>
This should open a URL such as
<c>random-words-123randomletters789-4000.app.github.dev</c>,
which will show a live preview of your GitHub Pages site in a new
tab. As soon as you make edits in your Codespace tab, you can
return to this tab to (within a second or two) see how your edits
will update your live site. Note that this URL is private to you,
and your public site won't be updated until you Commit &amp; Sync
your changes
(<xref ref="note-commit-sync"/>).
</p>
<p>
Personally, I use <c>GitHub.dev</c> (or even just the
<c>GitHub.com</c> edit button) rather than a full
Codespace when adding a quick post or making a quick edit on
many of my GitHub Pages websites. But the Codespace option is very
handy for when bigger changes are necessary, and you want to make
sure everything looks just right before pushing it live to the public.
</p>
</section>
</chapter>
2 changes: 1 addition & 1 deletion source/main.ptx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@

<xi:include href="ch-git-github.ptx"/>
<xi:include href="ch-first-repo.ptx"/>
<xi:include href="ch-website.ptx"/>
<xi:include href="ch-coding.ptx"/>
<xi:include href="ch-website.ptx"/>
<xi:include href="ch-collaboration.ptx"/>
<xi:include href="ch-jupyter.ptx"/>
<xi:include href="ch-projects.ptx"/>
Expand Down
Loading