How do programmers communicate about code?

11. How do programmers communicate about code?#

11.1. Commit messages are essential#

A git commit message must exist and is always for people, but can also be for machines.

The conventional commits standard is a format of commits

If you use this, then you can use automated tools to generate a full change log when you release code

Tooling and examples of conventional commits

That is a core example of the types of detailed communication we do in programming that is embedded into the work.

Where else have you seen how communication about the work shape the work

11.2. Why Documentation#

Today we will talk about documentation, there are several reasons this is important:

  • using official documentation is the best way to get better at the tools

  • understanding how documentation is designed and built will help you use it better

  • writing and maintaining documentation is really important part of working on a team

  • documentation building tools are a type of developer tool (and these are generally good software design)

Design is best learned from examples. Some of the best examples of software design come from developer tools.

In particular documentation tools are really good examples of:

  • pattern matching

  • modularity and abstraction

  • automation

  • the build process beyond compiling

By the end of today’s class you will be able to:

  • describe different types of documentation

  • find different information in a code repo

  • generate documentation as html

  • create a repo locally and push to GitHub

Plus we will reinforce things we have already seen:

  • ignoring content from a repo

  • paths

  • good file naming

11.3. What is documentation#

documentation types table

from ethnography of docuemtnation data science

11.3.1. Why is documentation so important?#

we should probably spend more time on it

differenc ein time spent vs should

via source

11.4. So, how do we do it?#

Different types of documentation live in different places and we can use tools to maintain them.

As developers, we rely on code to do things that are easy for computers and hard for people.

Documenation Tools

write the docs

linux kernel uses sphinx and here is why and how it works

Why is there so much emphasis on documentation?

Back in the early days of programming, developers were primarily focused on writing code and achieving functional results. There were no established disciplines that enforced best practices for testing, modularity, or documentation.

As a result, programmers often wrote large, complex chunks of code with little to no explanation of how they worked. Variable names were frequently arbitrary, such as 1, 2, a, b, z, or sproviding no meaningful context.

Do those names convey anything useful to you? Probably not. Now, imagine encountering them in a 500+ line program. The only way to understand their purpose would be to manually track every instance of their use—an exhausting and error-prone process.

This lack of clarity led to major challenges in code maintenance, collaboration, and debugging. As software development evolved, so did the need for structured documentation. Today, well-documented code is considered a best practice, ensuring that projects remain understandable, scalable, and maintainable over time.

11.5. Jupyterbook#

Jupyterbook wraps sphinx and uses markdown instead of restructured text. The project authors note in the documenation that it “can be thought of as an opinionated distribution of Sphinx”. We’re going to use this on our kwl repos.

navigate to your folder for this course (mine is Documents/systems)

cd Documents/systems/

We can confirm that jupyter-book is installed by checking the version.

jupyter-book --version

$ jupyter-book --version
Jupyter Book      : 1.0.3
External ToC      : 1.0.1
MyST-Parser       : 2.0.0
MyST-NB           : 1.2.0
Sphinx Book Theme : 1.1.4
Jupyter-Cache     : 1.0.1
NbClient          : 0.10.2

We will run a command to create a jupyterbook from a template, the command has 3 parts:

  • jupyter-book is a program (the thing we installed)

  • create is a subcommand (one action that program can do)

  • tiny-book is an argument (a mandatory input to that action)

jupyter-book create tiny-book

===============================================================================

Your book template can be found at

    tiny-book/

===============================================================================

We see that it succeeds

You can make it with any name:

jupyter-book create examplew

===============================================================================

Your book template can be found at

    examplew\

===============================================================================

beacuse the name is an argument or input

Each one makes a directory, we can see by listing

ls

examplew/            spring25-kwl-AymanBx/
gh-inclass-AymanBx/  tiny-book/

And we can delete the second one since we do not actually want it.

rm examplew/

rm: examplew/: is a directory

we get an error because it is not well defined to delete a directory, and potentially risky, so rm is written to throw an error

Usually to remove a directory with the rm command we use the -d option

rm -d examplew/

rm: cannot remove 'examplew/': Directory not empty

Notice, we still got an error, but this time the error is different, It’s telling us that the directory isn’t empty. So this means the -d option is only for empty directories.

Instead, we have to tell it two additional things:

  • to delete recusively r

  • to force it to do something risky with f (not really neccessary for this situation)

note we can stack single character options together with a single -. This means

rm -rf examplew/

We use the -r because we’re not just deleting examplew/. We’re deleting examplew/_toc.yml examplew/_configure.yml examplew/requirements.txt examplew/... . . .

And that’s why the need the recursion.

cd tiny-book/
ls

_config.yml  logo.png               notebooks.ipynb
_toc.yml     markdown-notebooks.md  references.bib
intro.md     markdown.md            requirements.txt

What happens if I used the -a option? We list all files, including hidden ones. What about -l? It actually lists all files in a list one item at a line with some more details about each file on the same line. Details related to write/read permissions on the file, owner of file and what not…

And because we can stack single letter options together we can do

ls -la

total 47
drwxr-xr-x 1 ayman 197609    0 Feb 24 20:43 ./
drwxr-xr-x 1 ayman 197609    0 Mar  4 13:03 ../
-rw-r--r-- 1 ayman 197609 1000 Feb 24 20:43 _config.yml
-rw-r--r-- 1 ayman 197609  180 Feb 24 20:43 _toc.yml
-rw-r--r-- 1 ayman 197609  431 Feb 24 20:43 intro.md
-rw-r--r-- 1 ayman 197609 9854 Feb 24 20:43 logo.png
-rw-r--r-- 1 ayman 197609 1787 Feb 24 20:43 markdown-notebooks.md
-rw-r--r-- 1 ayman 197609 1890 Feb 24 20:43 markdown.md
-rw-r--r-- 1 ayman 197609 3378 Feb 24 20:43 notebooks.ipynb
-rw-r--r-- 1 ayman 197609 5524 Feb 24 20:43 references.bib
-rw-r--r-- 1 ayman 197609   30 Feb 24 20:43 requirements.txt

11.5.1. Structure of a Jupyter book#

We will explore the output by looking at the files

ls

_config.yml		logo.png		notebooks.ipynb
_toc.yml		markdown-notebooks.md	references.bib
intro.md		markdown.md		requirements.txt

A jupyter book has two required files (_config.yml and _toc.yml), some for content, and some helpers that are common but not required.

  • config defaults

  • toc file formatting rules

  • the *.md files are content

  • the .bib file is bibiolography information

  • The other files are optional, but common. Requirements.txt is the format for pip to install python depndencies. There are different standards in other languages for how to specify requirenments and organize files that make up a packege

the extention (.yml) is yaml, which stands for “YAML Ain’t Markup Language”. It consists of key, value pairs and is deigned to be a human-friendly way to encode data for use in any programming language.

Note

the extention (.yml) is yaml, which stands for “YAML Ain’t Markup Language”. It consists of key, value pairs and is deigned to be a human-friendly way to encode data for use in any programming language.

11.5.2. Dev tools mean we do not have to write bibliographies manually#

bibliographies are generated with bibtex which takes structured information from the references in a bibtex file with help from sphinxcontrib-bibtex

For general reference, reference managers like zotero and mendeley can track all of your sources and output the references in bibtex format that you can use anywhere or sync with tools like MS Word or Google Docs.

cat _config.yml 

# Book settings
# Learn more at https://jupyterbook.org/customize/config.html

title: My sample book
author: The Jupyter Book Community
logo: logo.png

# Force re-execution of notebooks on each build.
# See https://jupyterbook.org/content/execute.html
execute:
  execute_notebooks: force

# Define the name of the latex output file for PDF builds
latex:
  latex_documents:
    targetname: book.tex

# Add a bibtex file so that we can create citations
bibtex_bibfiles:
  - references.bib

# Information about where the book exists on the web
repository:
  url: https://github.com/executablebooks/jupyter-book  # Online location of your book
  path_to_book: docs  # Optional path to your book, relative to the repository root
  branch: master  # Which branch of the repository should be used when creating links (optional)

# Add GitHub buttons to your book
# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
html:
  use_issues_button: true
  use_repository_button: true

Compared to what we saw on the example configure file in the documentation of Jupyter-book posted in the link earlier. This looks pretty similar, missing the explaining comments at the end of every line. But here since this is YOUR book, you can edit the name, the author, copyright and whatnot…

The configuration file, tells jupyter-book basic iformation about the book, it provides all of the settings that jupyterbook and sphinx need to render the content as whatever output format we want.

The table of contents file describe how to put the other files in order.

cat _toc.yml 

:linenos:
# Table of contents
# Learn more at https://jupyterbook.org/customize/toc.html

The first two lines are comments, the pound sign # is a comment in bash and YAML. Here, the developers chose, in the template to put information about how to set up this file right in the template file. This is developers helping their users!

:linenos:
:lineno-start: 4
format: jb-book
root: intro

The next two lines are key value pairs that tell the high level settings

:linenos:
:lineno-start: 6
chapters:
- file: markdown
- file: notebooks
- file: markdown-notebooks

the end of the file shows a list of files that will be treated as chapters. This is also the syntax for a list in YAML, the list is named chapters and each item, starting with a - has a single key, file

Where have we seen a YAML list?

You can create a community badge that uses as the location of the “contribution” a link to the snipped to a set of lines in your main spring2025 repo that is a YAML list. This is valid as long as it is created by Friday 03/07.

The one last file tells us what dependencies we have

cat requirements.txt 

jupyter-book
matplotlib
numpy

If your book generates with error messages run pip install -r requirements.txt

11.6. Building Documentation#

We can transform from raw source to an output by building the book

jupyter-book build .

Running Jupyter-Book v1.0.3
Source Folder: C:\Users\ayman\Documents\systems\tiny-book
Config Path: C:\Users\ayman\Documents\systems\tiny-book\_config.yml
Output Path: C:\Users\ayman\Documents\systems\tiny-book\_build\html
Running Sphinx v7.4.7
loading translations [en]... done
making output directory... done
[etoc] Changing master_doc to 'intro'
checking bibtex cache... out of date
parsing bibtex file C:\Users\ayman\Documents\systems\tiny-book\references.bib... parsed 5 entries
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'linkify', 'dollarmath', 'colon_fence', 'substitution', 'tasklist'}, disable_syntax=[], all_links_external=False, url_schemes=('mailto', 'http', 'https'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
myst-nb v1.2.0: NbParserConfig(custom_formats={}, metadata_key='mystnb', cell_metadata_key='mystnb', kernel_rgx_aliases={}, eval_name_regex='^[a-zA-Z_][a-zA-Z0-9_]*$', execution_mode='force', execution_cache_path='', execution_excludepatterns=[], execution_timeout=30, execution_in_temp=False, execution_allow_errors=False, execution_raise_on_error=False, execution_show_tb=False, merge_streams=False, render_plugin='default', remove_code_source=False, remove_code_outputs=False, code_prompt_show='Show code cell {type}', code_prompt_hide='Hide code cell {type}', number_source_lines=False, output_stderr='show', render_text_lexer='myst-ansi', render_error_lexer='ipythontb', render_image_options={}, render_figure_options={}, render_markdown_format='commonmark', output_folder='build', append_css=True, metadata_to_fm=False)
Using jupyter-cache at: C:\Users\ayman\Documents\systems\tiny-book\_build\.jupyter_cache
sphinx-multitoc-numbering v0.1.3: Loaded
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 4 source files that are out of date
updating environment: [new config] 4 added, 0 changed, 0 removed
C:\Users\ayman\Documents\systems\tiny-book\markdown-notebooks.md: Executing notebook using local CWD [mystnb]
C:\Users\ayman\AppData\Roaming\Python\Python313\site-packages\zmq\_future.py:687: RuntimeWarning: Proactor event loop does not implement add_reader family of methods required for zmq. Registering an additional selector thread for add_reader support via tornado. Use `asyncio.set_event_loop_policy(WindowsSelectorEventLoopPolicy())` to avoid this warning.
  self._get_loop()
Assertion failed: Connection reset by peer [10054] (C:\Users\runneradmin\AppData\Local\Temp\tmpas55v6tq\build\_deps\bundled_libzmq-src\src\signaler.cpp:345)
C:\Users\ayman\Documents\systems\tiny-book\markdown-notebooks.md: Executed notebook in 2.60 seconds [mystnb]
C:\Users\ayman\Documents\systems\tiny-book\notebooks.ipynb: Executing notebook using local CWD [mystnb]
C:\Users\ayman\Documents\systems\tiny-book\notebooks.ipynb: Executed notebook in 8.73 seconds [mystnb]

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets...
copying static files... done
copying extra files... done
copying assets: done
writing output... [100%] notebooks
generating indices... genindex done
writing additional pages... search done
copying images... [100%] C:/Users/ayman/Documents/systems/tiny-book/_build/jupyter_execute/ee80d0a558444fcd144a2940dd28220cc9558f4121ae62c3dd86457f521a0b16.png
dumping search index in English (code: en)... done
dumping object inventory... done
[etoc] missing index.html written as redirect to 'intro.html'
build succeeded.

The HTML pages are in _build\html.

===============================================================================

Finished generating HTML for book.
Your book's HTML pages are here:
    _build\html\
You can look at your book by opening this file in a browser:
    _build\html\index.html
Or paste this line directly into your browser bar:
    file://C:\Users\ayman\Documents\systems\tiny-book\_build\html\index.html

===============================================================================

Try it yourself

Which files created by the template are not included in the rendered output? How could you tell?

Now we can look at what it did

ls

_build/      intro.md               markdown.md      requirements.txt
_config.yml  logo.png               notebooks.ipynb
_toc.yml     markdown-notebooks.md  references.bib

we note that this made a new folder called _build. we can look inside there.

ls _build/

html/  jupyter_execute/

and in the html folder:

ls _build/html/

_images/                index.html               objects.inv
_sources/               intro.html               search.html
_sphinx_design_static/  markdown-notebooks.html  searchindex.js
_static/                markdown.html
genindex.html           notebooks.html

We find the index.html file which is the interactive page we created with jupyter-book

We can also copy the path to the file and open it in our browser

we can change the size of a browser window or use the screen size settings in inspect mode to see that this site is responsive.

We didn’t have to write any html and we got a responsive site!

If we look at the content of the book we just created one of the pages is labeled Notebooks with MyST Markdown If we compare this with what we saw in the _toc.yml file we remember the last The last file listed is markdown-notebooks.md

Let’s check the content of the file

cat markdown-notebooks.md

---
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.11.5
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

# Notebooks with MyST Markdown

Jupyter Book also lets you write text-based notebooks using MyST Markdown.
See [the Notebooks with MyST Markdown documentation](https://jupyterbook.org/file-types/myst-notebooks.html) for more detailed instructions.
This page shows off a notebook written in MyST Markdown.

## An example cell

With MyST Markdown, you can define code cells with a directive like so:

\`\`\`{code-cell}
print(2 + 2)
\`\`\`

When your book is built, the contents of any `{code-cell}` blocks will be
executed with your default Jupyter kernel, and their outputs will be displayed
in-line with the rest of your content.

\`\`\`{seealso}
Jupyter Book uses [Jupytext](https://jupytext.readthedocs.io/en/latest/) to convert text-based files to notebooks, and can support [many other text-based notebook files](https://jupyterbook.org/file-types/jupytext.html).
\`\`\`

## Create a notebook with MyST Markdown

MyST Markdown notebooks are defined by two things:

1. YAML metadata that is needed to understand if / how it should convert text files to notebooks (including information about the kernel needed).
   See the YAML at the top of this page for example.
2. The presence of `{code-cell}` directives, which will be executed with your book.

That's all that is needed to get started!

## Quickly add YAML metadata for MyST Notebooks

If you have a markdown file and you'd like to quickly add YAML metadata to it, so that Jupyter Book will treat it as a MyST Markdown Notebook, run the following command:

\`\`\`
jupyter-book myst init path/to/markdownfile.md
\`\`\`

cool, we can see that the content of that page is derived directly from this file

If you wanted to change the styling with sphinx you can use built in themes which tell sphinx to put different files in the _static folder when it builds your site, but you don’t have to change any of your content! If you like working on front end things (which is great! it’s just not alwasy the goal) you can even build your own theme that can work with sphinx.

11.7. Starting a git repo locally#

We made this folder, but we have not used any git operations on it yet, it is actually not a git repo, which we could tell from the output above, but let’s use git to inspect and get another hint.

We can try git status

git status

fatal: not a git repository (or any of the parent directories): .git

This tells us the .git directory is missing form the current path and all parent directories. This is because we simply created this folder tiny-book it’s not linked to git whatsoever yet

To make it a git repo we use git init with the path we want to initialize, which currently is .

git init .

Initialized empty Git repository in C:/Users/ayman/Documents/systems/tiny-book/.git/

Let’s see what changed

ls -a

./       _config.yml  markdown-notebooks.md  requirements.txt
../      _toc.yml     markdown.md
.git/    intro.md     notebooks.ipynb
_build/  logo.png     references.bib

we got a .git/ folder

Let’s check if we succeeded

git status

On branch master

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        _build/
        _config.yml
        _toc.yml
        intro.md
        logo.png
        markdown-notebooks.md
        markdown.md
        notebooks.ipynb
        references.bib
        requirements.txt

nothing added to commit but untracked files present (use "git add" to track)

Here we are faced with a social aspect of computing that is also a good reminder about how git actually works

we’ll change our default branch to main

git branch -m main

and check in with git now

git status

On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    _build/
	_config.yml
	_toc.yml
	intro.md
	logo.png
	markdown-notebooks.md
	markdown.md
	notebooks.ipynb
	references.bib
	requirements.txt

nothing added to commit but untracked files present (use "git add" to track)

this time it works and we see a two important things:

  • there are no previous commits

  • all of the files are untracked

11.8. Handling Built files#

The built site files are compeltey redundant, content wise, to the original markdown files.

We do not want to keep track of changes for the built files since they are generated from the source files. It’s redundant and makes it less clear where someone should update content.

How can we tell it not to track the build folder?

Git helps us with this with the .gitignore

echo "_build" >> .gitignore

git status

On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
	.gitignore
    _config.yml
	_toc.yml
	intro.md
	logo.png
	markdown-notebooks.md
	markdown.md
	notebooks.ipynb
	references.bib
	requirements.txt

nothing added to commit but untracked files present (use "git add" to track)

only the .gitingore file is listed! But it took away the _build/ folder just as we want.

and we will commit the template.

git add .

warning: in the working copy of '.gitignore', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of '_config.yml', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of '_toc.yml', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of 'intro.md', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of 'markdown-notebooks.md', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of 'markdown.md', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of 'notebooks.ipynb', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of 'references.bib', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of 'requirements.txt', LF will be replaced by CRLF the next time Git touches it

We have to add separately because the files are untracked we cannot use the -a option on commit

This is GitBash telling you that git is helping. Windows uses two characters for a new line CR (cariage return) and LF (line feed). Classic Mac Operating system used the CR character. Unix-like systems (including MacOS X) use only the LF character. If you try to open a file on Windows that has only LF characters, Windows will think it’s all one line. To help you, since git knows people collaborate across file systems, when you check out files from the git database (.git/ directory) git replaces LF characters with CRLF before updating your working directory.

When working on Windows, when you make a file locally, each new line will have CRLF in it. If your collaborator (or server, eg GitHub) runs not a unix or linux based operating system (it almost certainly does) these extra characters will make a mess and make the system interpret your code wrong. To help you out, git will automatically, for Windows users, convert CRLF to LF when it adds your work to the index (staging area). Then when you push, it’s the compatible version.

git documentation of the feature this is added to a new Windows page under resources

and then we will commit with a simple message

git commit -m 'jupyter book template'

[main (root-commit) 1da3fa4] jupyter book template
 10 files changed, 342 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 _config.yml
 create mode 100644 _toc.yml
 create mode 100644 intro.md
 create mode 100644 logo.png
 create mode 100644 markdown-notebooks.md
 create mode 100644 markdown.md
 create mode 100644 notebooks.ipynb
 create mode 100644 references.bib
 create mode 100644 requirements.txt

11.9. How do I push a repo that I made locally to GitHub?#

Right now, we do not have any remotes, so if we try to push it will fail. Next we will see how to fix that.

First let’s confirm

git push

fatal: No configured push destination.
Either specify the URL from the command-line or configure a remote repository using

    git remote add <name> <url>

and then push using the remote name

    git push <name>

and it tells us how to fix it. This is why inspection is so powerful in developer tools, that is where we developers give one another hints.

Right now, we do not have any remotes

git remote

For today, we will create an empty github repo shared with me, by accepting the assignment linked in prismia or ask a TA/instructor if you are making up class.

More generally, you can create a repo

That default page for an empty repo if you do not initiate it with any files will give you the instructions for what remote to add.

Now we add the remote

git remote add origin https://github.com/compsys-progools/tiny-book-aymanbx-1.git

We can see what it did

git remote

origin

git status

On branch main
nothing to commit, working tree clean

Remember, It doesn’t mention anything about whether we’re ahead or behind with origin/main That’s because we haven’t linked the two branches together yet.

git push

fatal: The current branch main has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin main

To have this happen automatically for branches without a tracking
upstream, see 'push.autoSetupRemote' in 'git help config'.

git gives us advise on what to do

git push -u origin main

To https://github.com/compsys-progtools/tiny-book-AymanBx
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'https://github.com/compsys-progtools/tiny-book-AymanBx'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref. If you want to integrate the remote changes, use
hint: 'git pull' before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

This is telling us that there is a commit on the GitHub repo that doesn’t exist locally so the two repos are out of sync.

(We haven’t made any changes ourselves on GitHub but when we create a repo on GitHub we get an initial commit)

git pull

remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 5 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Unpacking objects: 100% (5/5), 1.70 KiB | 102.00 KiB/s, done.
From https://github.com/compsys-progtools/tiny-book-AymanBx
 * [new branch]      feedback   -> origin/feedback
 * [new branch]      main       -> origin/main
There is no tracking information for the current branch.
Please specify which branch you want to merge with.
See git-pull(1) for details.

    git pull <remote> <branch>

If you wish to set tracking information for this branch you can do so with:

    git branch --set-upstream-to=origin/<branch> main

This is telling us to that since the previous pull command didn’t execute successfuly we still haven’t linked the local main with the online main and we need to git pull -u origin main

11.10. Prepare for Next Class#

  1. review the notes on what is a commit. In gitdef.md on the branch for this issue, try to describe git in the four ways we described a commit. the point here is to think about what you know for git and practice remembering it, not “get the right answer”; this is prepare work, we only check that it is complete, not correct

  2. Start recording notes on how you use IDEs for the next couple of weeks using the template file below. We will come back to these notes in class later, but it is best to record over a time period instead of trying to remember at that time. Store your notes in your fall24 repo in idethoughts.md on a dedicated ide_prep branch. This is prep for after a few weeks from now, not for October 8; keep this branch open until it is specifically asked for

11.11. Experience Report Evidence#

11.12. Badges#

  1. Review the notes, jupyterbook docs, and experiment with the jupyter-book CLI to determine what files are required to make jupyter-book build run. Make your kwl repo into a jupyter book, by manually adding those files. do not add the whole template to your repo, make the content you have already so it can build into html. Set it so that the _build directory is not under version control.

  2. Add docs-review.md to your KWL repo and explain the most important things to know about documentation in your own words using other programming concepts you have learned so far. Include in a markdown (same as HTML <!-- comment --> ) comment the list of CSC courses you have taken for context while we give you feedback.

  1. Review the notes, jupyterbook docs, and experiment with the jupyter-book CLI to determine what files are required to make jupyter-book build run. Make your kwl repo into a jupyter book. Set it so that the _build directory is not under version control.

  2. Learn about the documentation ecosystem in another language that you know using at least one official source and additional sources as you find helpful. In docs-practice.md include a summary of your findings and compare and contrast it to jupyter book/sphinx. Include a bibtex based bibliography of the sources you used. You can use this generator for informal sources and google scholar for formal sources (or a reference manager).

11.13. Questions#

Contents