doc: Update for GitLab support (#487)

Update documentation website to reflect the new GitLab support
from #477.

refs #485

Author: abhinav

README.md

@@ -14,7 +14,7 @@
 git-spice is a tool for stacking Git branches.
 It lets you manage and navigate stacks of branches,
 conveniently modify and rebase them,
-and create GitHub Pull Requests from them.
+and create GitHub Pull Requests or GitLab Merge Requests from them.
 
 See <https://abhinav.github.io/git-spice/> for more details.
 
@@ -24,7 +24,7 @@ Usage looks roughly like this:
 # Stack a branch on top of the current branch.
 $ gs branch create feat1
 
-# Stack aonther branch on top of feat1.
+# Stack another branch on top of feat1.
 $ gs branch create feat2
 
 # Submit pull requests for feat1 and feat2.
@@ -51,8 +51,8 @@ $ gs sr        # stack restack
 ## Features
 
 - Create, edit, and navigate stacks of branches with ease.
-- Create and update GitHub Pull Requests for the entire stack
-  or parts of it with a single command.
+- Submit the entire stack or parts of it with a single command.
+  Supports GitHub and GitLab.
 - Keep using your existing workflow and adopt git-spice incrementally.
 - Completely offline operation with no external dependencies
   until you push or pull from a remote repository.

doc/hooks/badge.py

@@ -0,0 +1,44 @@
+"""
+Adds a badgge shortcode in the form:
+
+    <!-- gs:badge ICON TEXT -->
+
+Where ICON is a mkdocs-material icon name
+and TEXT is the text to display.
+"""
+
+import re
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import Files
+from mkdocs.structure.pages import Page
+
+_tag_re = re.compile(r'<!-- gs:badge ([^ ]+) (.+?) -->')
+
+
+def on_page_markdown(
+    markdown: str,
+    page: Page,
+    config: MkDocsConfig,
+    files: Files,
+    **kwargs
+) -> str:
+    def replace(match: re.Match) -> str:
+        icon = match.group(1)
+        text = match.group(2)
+        return ''.join([
+            '<span class="mdx-badge">',
+            *[
+                '<span class="mdx-badge__icon">',
+                f':{icon}:',
+                '</span>',
+            ],
+            *[
+                '<span class="mdx-badge__text">',
+                text,
+                '</span>',
+            ],
+            '</span>'
+        ])
+
+    return _tag_re.sub(replace, markdown)

doc/hooks/replace.py

@@ -0,0 +1,27 @@
+"""
+Simple text replacement hooks.
+"""
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import Files
+from mkdocs.structure.pages import Page
+
+
+REPLACEMENTS = {
+    '<!-- gs:github -->': ':simple-github: GitHub',
+    '<!-- gs:gitlab -->': ':simple-gitlab: GitLab',
+    '<!-- gs:badge:github ': '<!-- gs:badge simple-github GitHub ',
+    '<!-- gs:badge:gitlab ': '<!-- gs:badge simple-gitlab GitLab ',
+}
+
+
+def on_page_markdown(
+    markdown: str,
+    page: Page,
+    config: MkDocsConfig,
+    files: Files,
+    **kwargs
+) -> str:
+    for key, value in REPLACEMENTS.items():
+        markdown = markdown.replace(key, value)
+    return markdown

doc/includes/captures/forge-prompt.txt

@@ -0,0 +1,4 @@
+Select a Forge: 
+
+▶ github
+  gitlab

doc/mkdocs.yml

@@ -46,6 +46,7 @@ theme:
   features:
     - content.action.edit
     - content.code.copy
+    - content.tabs.link
     - content.tooltips
     - header.autohide
     - navigation.expand
@@ -68,13 +69,16 @@ plugins:
   - redirects:
       redirect_maps:
         'how-to.md': 'recipes.md'
+        'guide/pr.md': 'guide/cr.md'
   - search
   - social:
       enabled: !ENV [CI, false]
 
 hooks:
+  - hooks/replace.py
   - hooks/cliref.py
   - hooks/released.py
+  - hooks/badge.py
   - hooks/footer.py
   - hooks/freeze.py
   - hooks/listing.py
@@ -110,7 +114,7 @@ nav:
     - guide/index.md
     - guide/concepts.md
     - guide/branch.md
-    - guide/pr.md
+    - guide/cr.md
     - guide/limits.md
     - guide/internals.md
   - Setting up:

doc/src/cli/config.md

@@ -76,13 +76,20 @@ See also: [GitHub Enterprise](../setup/auth.md#github-enterprise).
 URL of the GitLab instance used for GitLab requests.
 Defaults to `$GITLAB_URL` if set, or `https://gitlab.com` otherwise.
 
+See also [GitLab Self-Hosted](../setup/auth.md#gitlab-self-hosted).
+
 ### spice.forge.gitlab.oauth.clientID
 
 <!-- gs:version unreleased -->
 
 Client ID for OAuth authentication with GitLab.
-Default to git-spice's built-in Client ID in https://gitlab.com. 
-It should be set to a custom value if you are running your own GitLab Self-Managed instance.
+
+Defaults to git-spice's built-in Client ID (valid only for https://gitlab.com)
+or `$GITLAB_OAUTH_CLIENT_ID` if set.
+
+For Self-Hosted GitLab instances, you must set this value to a custom Client ID.
+
+See also [GitLab Self-Hosted](../setup/auth.md#gitlab-self-hosted).
 
 ### spice.log.all
 

doc/src/faq.md

@@ -31,17 +31,17 @@ keeping them up-to-date and in sync with each other.
 
 - [The stacking workflow](https://www.stacking.dev/)
 
-## Where is the GitHub authentication token stored?
+## Where is the authentication token stored?
 
 git-spice stores the GitHub authentication in a system-specific secure storage.
 See [Authentication > Safety](setup/auth.md#safety) for details.
 
-## Why doesn't git-spice create one PR per commit?
+## Why doesn't git-spice create one CR per commit?
 
 With tooling like this, there are two options:
 each commit is an atomic unit of work, or each branch is.
 While the former might be more in line with Git's original philosophy,
-the latter is more practical for most teams with GitHub-based workflows.
+the latter is more practical for most teams with GitHub or GitLab-based workflows.
 
 With a PR per commit, when a PR gets review feedback,
 you must amend that commit with fixes and force-push.
@@ -52,7 +52,7 @@ However, with a PR per branch, you can keep the original changes separate
 from follow-up fixes, even if the branch is force-pushed.
 This makes it easier for PR reviewers to work through the changes.
 
-And with GitHub squash-merges, you can still get a clean history
+And with squash-merges, you can still get a clean history
 consisting of atomic, revertible commits on the trunk branch.
 
 ## How does git-spice interact with `rebase.updateRefs`?

doc/src/guide/branch.md

@@ -1,5 +1,5 @@
 ---
-title: Branch stacks
+title: Local stacks
 icon: octicons/git-branch-16
 description: >-
   Manage, navigate, and manipulate stacks of branches with git-spice.

doc/src/guide/concepts.md

@@ -82,6 +82,15 @@ text "Sibling" with s at F.n
     This is "main" or "master" in most repositories.
     Trunk is the only branch that does not have a base branch.
 
+**Change Request**
+:   Change Request refers to a single merge-able unit of work
+    submitted to GitHub or GitLab.
+    Each Change Request corresponds to a branch.
+    On GitHub, these are called Pull Requests,
+    and on GitLab, they are called Merge Requests.
+    Since git-spice supports both platforms,
+    the term Change Request is used to refer to both.
+
 **Stack**
 :   A stack is a collection of branches stacked on top of each other
     in a way that each branch except the trunk has a base branch.

doc/src/guide/pr.md renamed to doc/src/guide/cr.md

@@ -1,24 +1,36 @@
 ---
-title: PR stacks
+title: Submitting stacks
 icon: octicons/git-pull-request-16
 description: >-
-  Create and update stacked pull requests from a stack of branches.
+  Create and update stacked change requests from a stack of branches.
 ---
 
-# Working with Pull Requests
+# Working with remote repositories
 
 !!! note
 
-    This page assumes you're using git-spice with GitHub.
-    If you're using a different Git hosting service,
-    you can still use git-spice, but some features may not be available.
+    This page assumes you are using one of the supported Git forges.
+    These are:
+
+    - <!-- gs:github -->
+    - <!-- gs:gitlab --> (<!-- gs:version unreleased -->)
+
+    If you're using a different service,
+    you can still use git-spice,
+    but some features may not be available.
 
     See:
 
-    - [:material-tooltip-check: Recipes > Working with non-GitHub remotes](../recipes.md#working-with-non-github-remotes)
+    - [:material-tooltip-check: Recipes > Working with unsupported remotes](../recipes.md#working-with-unsupported-remotes)
     - [:material-frequently-asked-questions: FAQ > Will git-spice add support for other Git hosting services](../faq.md#will-git-spice-add-support-for-other-git-hosting-services)
 
-## Submitting pull requests
+## Submitting change requests
+
+!!! info
+
+    git-spice uses the term *Change Request* to refer to submitted branches.
+    These corespond to Pull Requests on GitHub,
+    and to Merge Requests on GitLab.
 
 When your local changes are ready,
 use the following commands to submit your changes upstream:
@@ -33,10 +45,10 @@ use the following commands to submit your changes upstream:
   submits all branches in the stack
 
 Branch submission is an idempotent operation:
-pull requests will be created for branches that don't already have them,
+change requests will be created for branches that don't already have them,
 and updated for branches that do.
 
-For new pull requests, these commands will prompt you for PR information.
+For new change requests, these commands will prompt you for CR information.
 For example:
 
 ```freeze language="ansi"
@@ -52,11 +64,17 @@ For example:
 
 ### Navigation comments
 
-Pull Requests created by git-spice will include a navigation comment
+Change Requests created by git-spice will include a navigation comment
 at the top with a visual representation of the stack,
 and the position of the current branch in it.
 
-![Example of a stack navigation comment](../img/stack-comment.png)
+=== "<!-- gs:github -->"
+
+    ![Example of a stack navigation comment on GitHub](../img/stack-comment.png)
+
+=== "<!-- gs:gitlab -->"
+
+    ![Example of a stack navigation comment on GitLab](../img/stack-comment-glab.png)
 
 This behavior may be changed with the $$spice.submit.navigationComment$$
 configuration key.
@@ -86,7 +104,7 @@ you may also specify title and body directly.
 
 !!! info "Setting draft status non-interactively"
 
-    Pull requests may be marked as draft or ready for review
+    Change requests may be marked as draft or ready for review
     non-interactively with the `--draft` and `--no-draft` flags.
 
     By default, the submit commands will leave
@@ -123,35 +141,52 @@ This will update the trunk branch (e.g. `main`)
 with the latest changes from the upstream repository,
 and delete any local branches whose PRs have been merged.
 
-## Importing pull requests
+## Importing open CRs
 
-You can import an existing PR into git-spice
+You can import an existing open CR into git-spice
 by checking it out locally, tracking the branch with git-spice,
 and re-submitting it.
 
-For example, if you have the GitHub CLI installed:
+For example:
 
-```freeze language="terminal"
-{gray}# Check out the PR locally{reset}
-{green}${reset} gh pr checkout 359
+=== "<!-- gs:github -->"
 
-{gray}# Track it with git-spice{reset}
-{green}${reset} gs branch track
+    ```freeze language="terminal"
+    {gray}# Check out the PR locally{reset}
+    {green}${reset} gh pr checkout 359
 
-{gray}# Re-submit it{reset}
-{green}${reset} gs branch submit
-{green}INF{reset} comment-recovery: Found existing CR #359
-{green}INF{reset} CR #359 is up-to-date: https://github.com/abhinav/git-spice/pull/359
-```
+    {gray}# Track it with git-spice{reset}
+    {green}${reset} gs branch track
+
+    {gray}# Re-submit it{reset}
+    {green}${reset} gs branch submit
+    {green}INF{reset} comment-recovery: Found existing CR #359
+    {green}INF{reset} CR #359 is up-to-date: https://github.com/abhinav/git-spice/pull/359
+    ```
+
+=== "<!-- gs:gitlab -->"
+
+    ```freeze language="terminal"
+    {gray}# Check out the MR locally{reset}
+    {green}${reset} glab mr checkout 8
+
+    {gray}# Track it with git-spice{reset}
+    {green}${reset} gs branch track
+
+    {gray}# Re-submit it{reset}
+    {green}${reset} gs branch submit
+    {green}INF{reset} reticulating-splines: Found existing CR !8
+    {green}INF{reset} CR !8 is up-to-date: https://gitlab.com/abg/test-repo/-/merge_requests/8
+    ```
 
 !!! important
 
     For this to work, the following MUST all be true:
 
-    - The PR is pushed to a branch in the upstream repository
+    - The CR is pushed to a branch in the upstream repository
     - The local branch name exactly matches the upstream branch name
 
-This will work even for PRs that were not created by git-spice,
+This will work even for CRs that were not created by git-spice,
 or authored by someone else, as long as the above conditions are met.
 
 In <!-- gs:version v0.5.0 --> or newer,