glossary and intersphinx to git-intro

Author: rkdarst

content/concepts.md

@@ -21,13 +21,13 @@
 
 ## Commits, branches, repositories, forks, clones
 
-- **repository**: The project, contains all data and history (commits, branches, tags).
-- **commit**: Snapshot of the project, gets a unique identifier (e.g. `c7f0e8bfc718be04525847fc7ac237f470add76e`).
-- **branch**: Independent development line. The main development line is often called `main`.
-- **tag**: A pointer to one commit, to be able to refer to it later. Like a [commemorative plaque](https://en.wikipedia.org/wiki/Commemorative_plaque)
+- {term}`repository`: The project, contains all data and history (commits, branches, tags).
+- {term}`commit`: Snapshot of the project, gets a unique identifier (e.g. `c7f0e8bfc718be04525847fc7ac237f470add76e`).
+- {term}`branch`: Independent development line. The main development line is often called `main`.
+- {term}`tag`: A pointer to one commit, to be able to refer to it later. Like a [commemorative plaque](https://en.wikipedia.org/wiki/Commemorative_plaque)
   that you attach to a particular commit (e.g. `phd-printed` or `paper-submitted`).
-- **cloning**: Copying the whole repository to your laptop - the first time. It is not necessary to download each file one by one.
-- **forking**: Taking a copy of a repository (which is typically not yours) - your
+- {term}`cloning <clone>`: Copying the whole repository to your laptop - the first time. It is not necessary to download each file one by one.
+- {term}`forking <fork>`: Taking a copy of a repository (which is typically not yours) - your
   copy (fork) stays on GitHub/GitLab and you can make changes to your copy.
 
 

content/conf.py

@@ -37,6 +37,7 @@
     # remove once sphinx_rtd_theme updated for contrast and accessibility:
     "sphinx_rtd_theme_ext_color_contrast",
     "sphinx_coderefinery_branding",
+    "sphinx.ext.intersphinx",
 ]
 
 # MyST extensions
@@ -65,6 +66,10 @@
     "img/README.md",
 ]
 
+intersphinx_mapping = {
+    'git-intro': ('https://coderefinery.github.io/git-intro/', None)    }
+
+
 
 # -- Options for HTML output -------------------------------------------------
 

content/reference.md

@@ -12,28 +12,57 @@ the basics.
 
 ## Glossary
 
-* **remote**: Roughly, another git repository on another computer.  A
-  repository can be linked to several other remotes.
-* **push**: Send a branch from your current repository to another repository
-* **fetch**: Update your view of another repository
-* **pull**: Fetch (above) and then merge
-* **origin**: Default name for a remote repository.
-* **origin/NAME**: A branch name which represents a remote branch.
-* **main**: Default name for main branch.
-* **merge**: Combine the changes on two branches.
-* **conflict**: When a merge has changes that affect the same lines,
-  git can not automatically figure out what to do.  It presents the
-  conflict to the user to resolve.
-* **issue**: Feature of web repositories that allows discussion
-  related to a repository.
-* **pull request**: A GitHub/Gitlab feature that allows you to send a
-  code suggestion using a branch, which allows one-button merging.  In
-  Gitlab, called "**merge request**".
-* **git hook**: Code that can run before or after certain actions, for
-  example to do tests before allowing you to commit.
-* **bare repository**: A copy of a repository that only is only the `.git`
-  directory: there are no files actually checked out.  Directory names
-  usually like `something.git`
+:::{glossary}
+
+remote
+   Roughly, another git repository on another computer.  A
+   repository can be linked to several other remotes.
+
+push
+   Send a branch from your current repository to another repository
+
+fetch
+   Update your view of another repository
+
+pull
+   Fetch (above) and then merge
+
+origin
+   Default name for a remote repository.
+
+origin/NAME
+   A branch name which represents a remote branch.
+
+main
+   Default name for main branch.
+
+merge
+   Combine the changes on two branches.
+
+conflict
+   When a merge has changes that affect the same lines,
+   git can not automatically figure out what to do.  It presents the
+   conflict to the user to resolve.
+
+issue
+   Feature of web repositories that allows discussion
+   related to a repository.
+
+pull request
+   A GitHub/Gitlab feature that allows you to send a
+   code suggestion using a branch, which allows one-button merging.  In
+   Gitlab, called "**merge request**".
+
+git hook
+   Code that can run before or after certain actions, for
+   example to do tests before allowing you to commit.
+
+bare repository
+   A copy of a repository that only is only the `.git`
+   directory: there are no files actually checked out.  Directory names
+   usually like `something.git`
+
+:::
 
 
 ## Commands we use