Add Nox commands & CONTRIBUTING instructions for Spyder submodule

Author: CAM-Gerlach

.gitmodules

@@ -2,3 +2,4 @@
 	path = spyder
 	url = https://github.com/spyder-ide/spyder.git
 	branch = 6.x
+	update = rebase

CONTRIBUTING.md

@@ -58,10 +58,10 @@ If referring to a specific line or file, please be sure to provide a snippet of
 ## Cloning the Repository
 
 First, navigate to the [project repository](https://github.com/spyder-ide/spyder-api-docs) in your web browser and press the ``Fork`` button to make a personal copy of the repository on your own GitHub account.
-Then, click the ``Clone or Download`` button on your repository, copy the link and run the following on the command line to clone the repo:
+Then, click the ``Clone or Download`` button on your repository, copy the link and run the following on the command line to clone the repo (with submodules):
 
 ```shell
-git clone <LINK-TO-YOUR-REPO>
+git clone --recurse-submodules <LINK-TO-YOUR-REPO>
 ```
 
 After cloning the repository, navigate to its new directory using the `cd` command:
@@ -119,6 +119,22 @@ For advanced users, if you'd prefer to also have your own local environment with
 **Note**: You may need to substitute ``python3`` for ``python`` in the commands below on some Linux distros where ``python`` isn't mapped to ``python3`` (yet).
 
 
+### Configure Git
+
+Make sure to set the upstream Git remote to the official Spyder-API-Docs repo with:
+
+```shell
+git remote add upstream https://github.com/spyder-ide/spyder-api-docs.git
+```
+
+It's also a good idea to configure Git to automatically pull, checkout and push submodules:
+
+```shell
+git config --local submodule.recurse true
+git config --local push.recurseSubmodules check
+```
+
+
 ### Create and activate a fresh environment
 
 We highly recommend you create and activate a virtual environment to avoid any conflicts with other packages on your system or causing any other issues.
@@ -178,15 +194,6 @@ python -m pip install -r requirements.txt
 ```
 
 
-### Add the upstream remote
-
-Make sure to set the upstream Git remote to the official Spyder-API-Docs repo with:
-
-```shell
-git remote add upstream https://github.com/spyder-ide/spyder-api-docs.git
-```
-
-
 
 ## Installing and Using the Pre-Commit Hooks
 
@@ -295,7 +302,40 @@ git switch -c <FEATURE-BRANCH>
 ```
 
 
-### Commit your changes
+### Sync the latest Spyder docstrings (optional)
+
+*If* your pull request requires the latest docstring changes from the Spyder repo, or there's a reason to manually update them, you can update the submodule to the latest stable branch either with Nox:
+
+```shell
+nox -s sync-spyder
+```
+
+or manually:
+
+```shell
+git submodule update --remote
+```
+
+**Note**: If using the manual command and you've checked out the submodule to a topic branch tracking your fork rather than the upstream Spyder repository, you'll need to either check out `6.x` first (setting it to track the main Spyder repo if it isn't already):
+
+```shell
+cd spyder
+git switch 6.x
+git --set-upstream-to upstream 6.x  # If required
+cd ..
+```
+
+Or, to integrate the changes into your own branch (assuming `upstream` is the Spyder repository):
+
+```shell
+cd spyder
+git fetch upstream 6.x
+git rebase FETCH_HEAD
+cd ..
+```
+
+
+### Make and commit your changes
 
 Once you've made and tested your changes, add them to the staging area, and then commit them with a descriptive message.
 Commit messages should be

noxfile.py

@@ -230,7 +230,7 @@ def _run(session):
     session.run(*posargs)
 
 
-@nox.session()
+@nox.session
 def run(session):
     """Run any command."""
     session.notify("_execute", posargs=([_run], *session.posargs))
@@ -257,6 +257,22 @@ def clean(session):
     _clean(session)
 
 
+def _sync_spyder(session):
+    """Sync the latest docstrings from upstream Spyder into the submodule."""
+    foreach_cmd = ["git", "submodule", "--quiet", "foreach"]
+    session.run(
+        *foreach_cmd,
+        "git fetch upstream 6.x && git rebase FETCH_HEAD",
+        external=True,
+    )
+
+
+@nox.session(name="sync-spyder")
+def sync_spyder(session):
+    """Sync the latest docstrings from upstream Spyder into the submodule."""
+    _sync_spyder(session)
+
+
 # --- Set up --- #
 
 
@@ -323,6 +339,41 @@ def setup_remotes(session):
     _setup_remotes(session)
 
 
+def _setup_submodule_remotes(session):
+    """Set up the upstream submodule remote to point to the Spyder repo."""
+    foreach_cmd = ["git", "submodule", "--quiet", "foreach"]
+    spyder_repo = "spyder"
+
+    # Check if an upstream remote already exists
+    existing_remotes = (
+        session.run(
+            *foreach_cmd,
+            "git remote",
+            external=True,
+            silent=True,
+            log=False,
+        ).strip().split("\n")
+    )
+
+    if "upstream" in existing_remotes:
+        return
+
+    spyder_repo_url = REPO_URL_HTTPS.format(user=ORG_NAME, repo=spyder_repo)
+    session.run(
+        *foreach_cmd,
+        f"git remote add upstream '{spyder_repo_url}'",
+        external=True,
+    )
+
+    session.run(*foreach_cmd, "git fetch --all", external=True)
+
+
+@nox.session(name="setup-submodule-remotes")
+def setup_submodule_remotes(session):
+    """Set up the upstream submodule remote to point to the Spyder repo."""
+    _setup_submodule_remotes(session)
+
+
 def _ignore_revs(session):
     """Configure the Git ignore revs file to the repo default."""
     if not IGNORE_REVS_FILE:
@@ -342,6 +393,50 @@ def ignore_revs(session):
     _ignore_revs(session)
 
 
+def _config_submodules(session):
+    """Configure Git to automatically recurse into Git submodules."""
+    session.run(
+        "git",
+        "config",
+        "--local",
+        "submodule.recurse",
+        "true",
+        external=True,
+    )
+    session.run(
+        "git",
+        "config",
+        "--local",
+        "push.recurseSubmodules",
+        "check",
+        external=True,
+    )
+
+
+@nox.session(name="config-submodules")
+def config_submodules(session):
+    """Initialize and download all Git submodules."""
+    _config_submodules(session)
+
+
+
+def _init_submodules(session):
+    """Initialize and download all Git submodules."""
+    session.run(
+        "git",
+        "submodule",
+        "update",
+        "--init",
+        external=True,
+    )
+
+
+@nox.session(name="init-submodules")
+def init_submodules(session):
+    """Initialize and download all Git submodules."""
+    _init_submodules(session)
+
+
 @nox.session()
 def setup(session):
     """Set up the project; pass --https or --ssh to specify Git URL type."""
@@ -350,6 +445,9 @@ def setup(session):
         posargs=(
             [
                 _ignore_revs,
+                _config_submodules,
+                _init_submodules,
+                _setup_submodule_remotes,
                 _setup_remotes,
                 _install_hooks,
                 _clean,