docs(git): Only update remote branches if asked¶
Description¶
Abstract¶
In git_to_sphinx.py, only fetch remote branches to update them locally if the GIT_TO_SPHINX_UPDATE_BRANCHES environment variable is set.
Force it to be set for CI when running make doc-string, and for readthedocs.
Motivation¶
When working on a branch, with some commits applied but not pushed to the origin, running git_to_sphinx (or by just doing make docs) reseted the branches to their remote head. so newly added commits where lost (not really, thanks to reflog)
Rationale¶
I chose to use a environment variable to make this choice really a choice, not an accident.
Info¶
- Hash
207325feae8d5731a59bfa368c08e2ade4e1f982
- Date
2020-09-25 23:37:37 +0200
- Parents
docs(git): Show source of renamed files [56390227] — 2020-09-25 23:37:36 +0200
- Children
docs(source): Make links between python files in source and git [04393b77] — 2020-09-25 23:40:13 +0200
- Branches
- Tags
(No tags)
Changes¶
.circleci/config.yml¶
- Type
Modified
- Stats
+1 -1
@@ -152,7 +152,7 @@ jobs:
name: Build documentation
command: |
source ~/venv/bin/activate
- make doc-strict
+ GIT_TO_SPHINX_UPDATE_BRANCHES=TRUE make doc-strict
# run check and tests for every commit in the history for which it is not already done
check_every_commit:
docs/conf.py¶
- Type
Modified
- Stats
+25 -8
@@ -123,17 +123,34 @@ def run_apidoc(_):
)
+def run_git_to_sphinx():
+ """Add git content into doc"""
+
+ update_remote_branches_env_var = "GIT_TO_SPHINX_UPDATE_BRANCHES"
+ update_remote_branches = os.environ.get(update_remote_branches_env_var)
+ if os.environ.get("READTHEDOCS"):
+ os.environ[update_remote_branches_env_var] = "TRUE"
+
+ try:
+ current_dir = os.path.dirname(__file__)
+ subprocess.run(
+ [
+ os.path.join(current_dir, "git_to_sphinx.py"),
+ os.path.normpath(os.path.join(current_dir, "..")),
+ os.path.normpath(os.path.join(current_dir, "source")),
+ ]
+ )
+ finally:
+ if not update_remote_branches and os.environ.get(
+ update_remote_branches_env_var
+ ):
+ del os.environ[update_remote_branches_env_var]
+
+
def setup(app):
# Run apidoc
app.connect("builder-inited", run_apidoc)
# Add custom css/js for rtd template
app.add_css_file("css/custom.css")
app.add_js_file("js/custom.js")
- # Add git content into doc
- current_dir = os.path.dirname(__file__)
- subprocess.run(
- [
- os.path.join(current_dir, "git_to_sphinx.py"),
- os.path.normpath(os.path.join(current_dir, "..")),
- ]
- )
+ run_git_to_sphinx()
docs/git_to_sphinx.py¶
- Type
Modified
- Stats
+42 -35
@@ -1,5 +1,9 @@
#!/usr/bin/env python
+# Set env `GIT_TO_SPHINX_UPDATE_BRANCHES` to other than empty string to update the remote branches
+# Careful: in dev environment it will reset all your local branches if they diverged from the
+# remove ones
+
import os
import re
import shutil
@@ -144,42 +148,45 @@ class RepositoryMining(RepositoryMiningBase):
# we need to fetch all branches:
repo = git_repo.repo
- # get remote branches not fetched yet
- existing_branches = {
- branch.name: branch.commit.hexsha for branch in repo.branches
- }
- remote_branches = {}
- for ref_info in repo.remote("origin").fetch():
- local_ref_name = ref_info.name.split("/", 1)[1]
- if ref_info.commit.hexsha != existing_branches.get(local_ref_name):
- remote_branches[local_ref_name] = ref_info.name
-
- if remote_branches:
- # save the current head
- head_detached = repo.head.is_detached
- if head_detached:
- current_ref = repo.head.commit
- else:
- current_ref = repo.head.ref
-
- # stash existing updates if needed
- with override_environ(**GIT_ENVIRON):
- stashed = "No local changes to save" not in repo.git.stash("save", "-u")
-
- # fetch remote branches not fetched yet
- for local_branch_name, remote_branch_name in remote_branches.items():
- repo.git.checkout("-B", local_branch_name, remote_branch_name)
-
- # restore previous head
- if head_detached:
- repo.git.checkout(current_ref.hexsha)
- else:
- current_ref.checkout()
-
- # and restore previous updates
- if stashed:
+ if os.environ.get("GIT_TO_SPHINX_UPDATE_BRANCHES"):
+ # get remote branches not fetched yet
+ existing_branches = {
+ branch.name: branch.commit.hexsha for branch in repo.branches
+ }
+ remote_branches = {}
+ for ref_info in repo.remote("origin").fetch():
+ local_ref_name = ref_info.name.split("/", 1)[1]
+ if ref_info.commit.hexsha != existing_branches.get(local_ref_name):
+ remote_branches[local_ref_name] = ref_info.name
+
+ if remote_branches:
+ # save the current head
+ head_detached = repo.head.is_detached
+ if head_detached:
+ current_ref = repo.head.commit
+ else:
+ current_ref = repo.head.ref
+
+ # stash existing updates if needed
with override_environ(**GIT_ENVIRON):
- repo.git.stash("pop")
+ stashed = "No local changes to save" not in repo.git.stash(
+ "save", "-u"
+ )
+
+ # fetch remote branches not fetched yet
+ for local_branch_name, remote_branch_name in remote_branches.items():
+ repo.git.checkout("-B", local_branch_name, remote_branch_name)
+
+ # restore previous head
+ if head_detached:
+ repo.git.checkout(current_ref.hexsha)
+ else:
+ current_ref.checkout()
+
+ # and restore previous updates
+ if stashed:
+ with override_environ(**GIT_ENVIRON):
+ repo.git.stash("pop")
# get the branch from the head now that we are sure we have all branches
git_repo._discover_main_branch(repo)