How do programmers communicate about code?

Today we are going to pick up from where we left off talking about the conventional commits.

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

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

• even if you use an LLM to help improve the writing, a human must verify the actual facts

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

• documentation building tools can help produce other types of writing in more developer-centric ways (nice automation of tedious things, etc)

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

• source (js version)

• source (python version)

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

What is documentation¶

We looked at a documentation types table from an article ethnography of documentation data science

Why is documentation so important?¶

we should probably spend more time on it

via source

So, how do we do it?¶

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

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

You can read a list of documentation tools built by the researchers at UC Berkeley who hosted a docathon, week long hackathon to help people get better at building documentation for the tools they used and built.

The site shows different tools for many different languages and a short description of many of the top tools.

There is even a whole community and site just for documentation: write the docs

Jupyterbook¶

Jupyterbook v1 wraps a tool called 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 goign to use this.

sphinx is a very popular tool so knowing how it works is a general advantage. reStructuredText is not hard to learn, but I did not want to spend time on that, so we’re using markdown to keep it simple, and to demonstrate that these tools are extensible.

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

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

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

jupyter-book --version

We will run a command to create a jupyterbook from a template:

jupyter-book create tiny-book

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

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

Your book template can be found at

    tiny-book/

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

We see that it succeeds

because the name is an argument or input, you can make it with any name:

jupyter-book create example

Each one makes a directory, we can see by listing

ls

gh-inclass-sp26-brownsarahm	tiny-book
kwl-sp26-brownsarahm  example

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

rm example/

rm: example/: 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

Instead, we have to tell it two additional things:

• to delete recusively r

• to force it to do something risky with f

note we can stack single character options together with a single -

rm -rf example/

Now, let’s move inside the new folder

cd tiny-book/

and look at what is there

ls -a

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

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.

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

git init .

hint: Using 'master' as the name for the initial branch. This default branch name
hint: will change to "main" in Git 3.0. To configure the initial branch name
hint: to use in all of your new repositories, which will suppress this warning,
hint: call:
hint:
hint: 	git config --global init.defaultBranch <name>
hint:
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint:
hint: 	git branch -m <name>
hint:
hint: Disable this message with "git config set advice.defaultBranchName false"
Initialized empty Git repository in /Users/brownsarahm/Documents/inclass/systems/tiny-book/.git/

+++{"lesson_part": "main"}

We want to use up to date, inclusive terminology, and we have already been using main for the default branch so far so let's do that again: 
```{code-cell} bash
:tags: ["skip-execution"]
git branch -m main
```

+++{"lesson_part": "site"}
::::::{important}
This is also a good reminder that branch names are just names of variables we choose, we can make them whatever we want, `git` does not care what they are.  We need branch names because otherwise we would have to keep track of commit hashes ourselves, but we can name them whatever we want. 

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

and we will commit the template.

git add .

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

and then we will commit with a simple message

git commit -m 'jupyter book template'

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

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 

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 

1
2
3
4
5
6
7
8
9
# Table of contents
# Learn more at https://jupyterbook.org/customize/toc.html

format: jb-book
root: intro
chapters:
- file: markdown
- file: notebooks
- file: markdown-notebooks

The one last file tells us what dependencies we have

cat requirements.txt

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

Building Documentation¶

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

jupyter-book build .

Running Jupyter-Book v1.0.4.post1
Source Folder: /Users/brownsarahm/Documents/inclass/systems/tiny-book
Config Path: /Users/brownsarahm/Documents/inclass/systems/tiny-book/_config.yml
Output Path: /Users/brownsarahm/Documents/inclass/systems/tiny-book/_build/html
Running Sphinx v7.4.7
loading translations [en]... done
[etoc] Changing master_doc to 'intro'
loading pickled environment... checking bibtex cache... up to date
done
myst v3.0.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'colon_fence', 'linkify', 'tasklist', 'substitution', 'dollarmath'}, disable_syntax=[], all_links_external=False, links_external_new_tab

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

ls _build/

and in the html folder:

ls _build/html/

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

we can change the size of a browswer 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 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.

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.

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

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

only the gitingore file itself is listed! just as we want.

now that’s the only new file as far as git is concerned, so we will track this,

git add .

and finally commit

git commit - 'ignore build'

error: pathspec '-' did not match any file(s) known to git
error: pathspec 'ignore build' did not match any file(s) known to git

I made a typo, so git said it couldn’t find files

git commit -m 'ignore build'

[main 7436ea1] ignore build
 1 file changed, 1 insertion(+)
 create mode 100644 .gitignore

Prepare for Next Class¶

Create a file gitcommandsbreakdown.md and for each command in the template below break down what steps it must do based on what we have learned so far about git objects. I started the first one as an example. Next class, we will make a commit using plumbing commands, so thinking about what you already know about commits will prepare you to learn this material.

# What git commands do

## `git status`

- check the branch of the HEAD pointer
- compare the HEAD pointer to the FETCH_HEAD, if different trace back through parent commits to find out how many commits apart they are and which is ahead (or if both ahead and behind)
- compare the snapshot at the HEAD pointer's commit to the current working directory
- if staging is not empty, compare that to the working directory

## `git commit`

- 

## `git add`

- 

Badges¶

Experience Report Evidence¶

Tiny book repo should exist. Append your terminal output or this repo’s git log to your experience report.

Questions After Today’s Class¶