My IPython-powered semi-automatic git workflow

  |   Source   |   Minimap   |   Note: Just click on any IPython input cell to see the output.

This is the last post of this year, so I try to do my best to give you something interesting to think about...

In this case, I will show you my git workflow... and you know there are a lot of workflows out there... and probably better than mine, but I just want to share with you the place where I find myself comfortable.

And yes... my git workflow is also powered by IPython (I am very repetitive when I love a project!). And it is a semi-automatic one, using the IPython notebooks (ipynbs) as a sort of templates, transforming them into a new conceptual entity: the ipytmpl (and yes, I love to invent names too!).

Because my workflow have essentially two cycles, in this post, I will show you the general set up of the environment and the first Short cycle, leaving the second Extended cycle (and other details) for other post (after the new year, of course).

I will also show you my workflow with a real PR (pull-request) to the IPython project.

Are you ready? Here we go...

Get everything ready...

First, we need to set up the environment to make our work:

  • Check the current working directory:
In [1]:
%pwd
  Click me!
Out[1]:
u'/media/datos/Desarrollos'
  • Make a new folder to isolate our work and cd into it:
In [2]:
!mkdir devel_example
  Click me!
In [3]:
%cd devel_example/
  Click me!
/media/datos/Desarrollos/devel_example

NOTE: You can avoid these steps opening the notebook in the proper directory, but in this case I want to have the example isolated to not overwrite my current development environment.

  • Load variables with useful information:
In [4]:
project_name = "ipython"
project_remote = "git://github.com/ipython/ipython.git"
project_remote_name = "origin"
my_fork_remote = "git@github.com:damianavila/ipython.git"
my_fork_remote_name = "damianavila"
  Click me!
  • Clone the project and connect the local repo with my Github fork:
In [5]:
# Get a read-only copy of the project
!git clone $project_remote

# cd into the local project folder
%cd $project_name

# Link the local repo with my Github fork
!git remote add $my_fork_remote_name $my_fork_remote

# Check remotes
!git remote -v
  Click me!
Clonar en «ipython»...
remote: Reusing existing pack: 96757, done.[K
remote: Counting objects: 82, done.[K
remote: Compressing objects:   1% (1/82)   [K
remote: Compressing objects:   2% (2/82)   [K
remote: Compressing objects:   3% (3/82)   [K
remote: Compressing objects:   4% (4/82)   [K
remote: Compressing objects:   6% (5/82)   [K
remote: Compressing objects:   7% (6/82)   [K
remote: Compressing objects:   8% (7/82)   [K
remote: Compressing objects:   9% (8/82)   [K
remote: Compressing objects:  10% (9/82)   [K
remote: Compressing objects:  12% (10/82)   [K
remote: Compressing objects:  13% (11/82)   [K
remote: Compressing objects:  14% (12/82)   [K
remote: Compressing objects:  15% (13/82)   [K
remote: Compressing objects:  17% (14/82)   [K
remote: Compressing objects:  18% (15/82)   [K
remote: Compressing objects:  19% (16/82)   [K
remote: Compressing objects:  20% (17/82)   [K
remote: Compressing objects:  21% (18/82)   [K
remote: Compressing objects:  23% (19/82)   [K
remote: Compressing objects:  24% (20/82)   [K
remote: Compressing objects:  25% (21/82)   [K
remote: Compressing objects:  26% (22/82)   [K
remote: Compressing objects:  28% (23/82)   [K
remote: Compressing objects:  29% (24/82)   [K
remote: Compressing objects:  30% (25/82)   [K
remote: Compressing objects:  31% (26/82)   [K
remote: Compressing objects:  32% (27/82)   [K
remote: Compressing objects:  34% (28/82)   [K
remote: Compressing objects:  35% (29/82)   [K
remote: Compressing objects:  36% (30/82)   [K
remote: Compressing objects:  37% (31/82)   [K
remote: Compressing objects:  39% (32/82)   [K
remote: Compressing objects:  40% (33/82)   [K
remote: Compressing objects:  41% (34/82)   [K
remote: Compressing objects:  42% (35/82)   [K
remote: Compressing objects:  43% (36/82)   [K
remote: Compressing objects:  45% (37/82)   [K
remote: Compressing objects:  46% (38/82)   [K
remote: Compressing objects:  47% (39/82)   [K
remote: Compressing objects:  48% (40/82)   [K
remote: Compressing objects:  50% (41/82)   [K
remote: Compressing objects:  51% (42/82)   [K
remote: Compressing objects:  52% (43/82)   [K
remote: Compressing objects:  53% (44/82)   [K
remote: Compressing objects:  54% (45/82)   [K
remote: Compressing objects:  56% (46/82)   [K
remote: Compressing objects:  57% (47/82)   [K
remote: Compressing objects:  58% (48/82)   [K
remote: Compressing objects:  59% (49/82)   [K
remote: Compressing objects:  60% (50/82)   [K
remote: Compressing objects:  62% (51/82)   [K
remote: Compressing objects:  63% (52/82)   [K
remote: Compressing objects:  64% (53/82)   [K
remote: Compressing objects:  65% (54/82)   [K
remote: Compressing objects:  67% (55/82)   [K
remote: Compressing objects:  68% (56/82)   [K
remote: Compressing objects:  69% (57/82)   [K
remote: Compressing objects:  70% (58/82)   [K
remote: Compressing objects:  71% (59/82)   [K
remote: Compressing objects:  73% (60/82)   [K
remote: Compressing objects:  74% (61/82)   [K
remote: Compressing objects:  75% (62/82)   [K
remote: Compressing objects:  76% (63/82)   [K
remote: Compressing objects:  78% (64/82)   [K
remote: Compressing objects:  79% (65/82)   [K
remote: Compressing objects:  80% (66/82)   [K
remote: Compressing objects:  81% (67/82)   [K
remote: Compressing objects:  82% (68/82)   [K
remote: Compressing objects:  84% (69/82)   [K
remote: Compressing objects:  85% (70/82)   [K
remote: Compressing objects:  86% (71/82)   [K
remote: Compressing objects:  87% (72/82)   [K
remote: Compressing objects:  89% (73/82)   [K
remote: Compressing objects:  90% (74/82)   [K
remote: Compressing objects:  91% (75/82)   [K
remote: Compressing objects:  92% (76/82)   [K
remote: Compressing objects:  93% (77/82)   [K
remote: Compressing objects:  95% (78/82)   [K
remote: Compressing objects:  96% (79/82)   [K
remote: Compressing objects:  97% (80/82)   [K
remote: Compressing objects:  98% (81/82)   [K
remote: Compressing objects: 100% (82/82)   [K
remote: Compressing objects: 100% (82/82), done.[K
Receiving objects:   0% (1/96839)   
Receiving objects:   0% (838/96839), 180.00 KiB | 163 KiB/s   
Receiving objects:   1% (969/96839), 180.00 KiB | 163 KiB/s   
Receiving objects:   2% (1937/96839), 356.00 KiB | 220 KiB/s   
Receiving objects:   2% (2517/96839), 532.00 KiB | 248 KiB/s   
Receiving objects:   3% (2906/96839), 532.00 KiB | 248 KiB/s   
Receiving objects:   4% (3874/96839), 724.00 KiB | 271 KiB/s   
Receiving objects:   4% (4028/96839), 724.00 KiB | 271 KiB/s   
Receiving objects:   5% (4842/96839), 916.00 KiB | 281 KiB/s   
Receiving objects:   6% (5811/96839), 1.11 MiB | 302 KiB/s   
Receiving objects:   6% (5934/96839), 1.11 MiB | 302 KiB/s   
Receiving objects:   7% (6779/96839), 1.36 MiB | 321 KiB/s   
Receiving objects:   8% (7748/96839), 1.63 MiB | 338 KiB/s   
Receiving objects:   8% (8211/96839), 1.63 MiB | 338 KiB/s   
Receiving objects:   9% (8716/96839), 1.63 MiB | 338 KiB/s   
Receiving objects:  10% (9684/96839), 1.93 MiB | 388 KiB/s   
Receiving objects:  10% (10510/96839), 2.19 MiB | 420 KiB/s   
Receiving objects:  11% (10653/96839), 2.19 MiB | 420 KiB/s   
Receiving objects:  12% (11621/96839), 2.19 MiB | 420 KiB/s   
Receiving objects:  13% (12590/96839), 2.54 MiB | 453 KiB/s   
Receiving objects:  14% (13558/96839), 2.54 MiB | 453 KiB/s   
Receiving objects:  14% (14032/96839), 2.97 MiB | 508 KiB/s   
Receiving objects:  15% (14526/96839), 2.97 MiB | 508 KiB/s   
Receiving objects:  16% (15495/96839), 3.47 MiB | 572 KiB/s   
Receiving objects:  16% (15566/96839), 3.47 MiB | 572 KiB/s   
Receiving objects:  17% (16463/96839), 4.04 MiB | 661 KiB/s   
Receiving objects:  17% (17318/96839), 4.71 MiB | 756 KiB/s   
Receiving objects:  17% (17390/96839), 6.39 MiB | 1.01 MiB/s   
Receiving objects:  18% (17432/96839), 7.40 MiB | 1.17 MiB/s   
Receiving objects:  18% (17660/96839), 8.42 MiB | 1.33 MiB/s   
Receiving objects:  18% (17826/96839), 10.43 MiB | 1.62 MiB/s   
Receiving objects:  19% (18400/96839), 11.39 MiB | 1.74 MiB/s   
Receiving objects:  20% (19368/96839), 11.39 MiB | 1.74 MiB/s   
Receiving objects:  21% (20337/96839), 12.39 MiB | 1.83 MiB/s   
Receiving objects:  21% (21161/96839), 12.39 MiB | 1.83 MiB/s   
Receiving objects:  22% (21305/96839), 12.39 MiB | 1.83 MiB/s   
Receiving objects:  22% (21760/96839), 13.82 MiB | 1.66 MiB/s   
Receiving objects:  22% (21963/96839), 13.88 MiB | 1.49 MiB/s   
Receiving objects:  22% (22221/96839), 14.14 MiB | 1.12 MiB/s   
Receiving objects:  23% (22273/96839), 14.14 MiB | 1.12 MiB/s   
Receiving objects:  23% (23228/96839), 14.57 MiB | 820 KiB/s   
Receiving objects:  24% (23242/96839), 14.57 MiB | 820 KiB/s   
Receiving objects:  24% (23563/96839), 15.26 MiB | 562 KiB/s   
Receiving objects:  25% (24210/96839), 15.64 MiB | 437 KiB/s   
Receiving objects:  25% (24276/96839), 16.49 MiB | 561 KiB/s   
Receiving objects:  25% (24281/96839), 16.95 MiB | 641 KiB/s   
Receiving objects:  25% (24393/96839), 18.11 MiB | 814 KiB/s   
Receiving objects:  26% (25179/96839), 18.80 MiB | 923 KiB/s   
Receiving objects:  27% (26147/96839), 18.80 MiB | 923 KiB/s   
Receiving objects:  28% (27115/96839), 18.80 MiB | 923 KiB/s   
Receiving objects:  28% (27486/96839), 19.55 MiB | 1.00 MiB/s   
Receiving objects:  29% (28084/96839), 19.55 MiB | 1.00 MiB/s   
Receiving objects:  30% (29052/96839), 19.55 MiB | 1.00 MiB/s   
Receiving objects:  31% (30021/96839), 19.55 MiB | 1.00 MiB/s   
Receiving objects:  32% (30989/96839), 19.55 MiB | 1.00 MiB/s   
Receiving objects:  32% (31754/96839), 20.81 MiB | 1.12 MiB/s   
Receiving objects:  33% (31957/96839), 20.81 MiB | 1.12 MiB/s   
Receiving objects:  34% (32926/96839), 20.81 MiB | 1.12 MiB/s   
Receiving objects:  35% (33894/96839), 21.17 MiB | 1.10 MiB/s   
Receiving objects:  36% (34863/96839), 21.17 MiB | 1.10 MiB/s   
Receiving objects:  36% (35541/96839), 21.17 MiB | 1.10 MiB/s   
Receiving objects:  37% (35831/96839), 21.53 MiB | 1.09 MiB/s   
Receiving objects:  38% (36799/96839), 21.53 MiB | 1.09 MiB/s   
Receiving objects:  38% (37615/96839), 21.89 MiB | 1.07 MiB/s   
Receiving objects:  38% (37632/96839), 22.96 MiB | 941 KiB/s   
Receiving objects:  39% (37768/96839), 23.32 MiB | 853 KiB/s   
Receiving objects:  39% (38133/96839), 23.32 MiB | 853 KiB/s   
Receiving objects:  40% (38736/96839), 23.68 MiB | 732 KiB/s   
Receiving objects:  40% (39474/96839), 24.04 MiB | 731 KiB/s   
Receiving objects:  41% (39704/96839), 24.40 MiB | 730 KiB/s   
Receiving objects:  41% (40563/96839), 24.77 MiB | 731 KiB/s   
Receiving objects:  42% (40673/96839), 25.13 MiB | 731 KiB/s   
Receiving objects:  43% (41641/96839), 25.13 MiB | 731 KiB/s   
Receiving objects:  44% (42610/96839), 25.49 MiB | 731 KiB/s   
Receiving objects:  45% (43578/96839), 25.49 MiB | 731 KiB/s   
Receiving objects:  45% (43720/96839), 25.85 MiB | 731 KiB/s   
Receiving objects:  45% (43735/96839), 26.21 MiB | 731 KiB/s   
Receiving objects:  45% (43740/96839), 27.29 MiB | 731 KiB/s   
Receiving objects:  45% (43748/96839), 27.95 MiB | 716 KiB/s   
Receiving objects:  45% (43834/96839), 28.38 MiB | 731 KiB/s   
Receiving objects:  46% (44546/96839), 29.10 MiB | 731 KiB/s   
Receiving objects:  47% (45515/96839), 29.10 MiB | 731 KiB/s   
Receiving objects:  47% (46175/96839), 29.10 MiB | 731 KiB/s   
Receiving objects:  48% (46483/96839), 29.10 MiB | 731 KiB/s   
Receiving objects:  49% (47452/96839), 29.46 MiB | 731 KiB/s   
Receiving objects:  50% (48420/96839), 29.46 MiB | 731 KiB/s   
Receiving objects:  51% (49388/96839), 29.46 MiB | 731 KiB/s   
Receiving objects:  52% (50357/96839), 29.82 MiB | 730 KiB/s   
Receiving objects:  52% (50871/96839), 29.82 MiB | 730 KiB/s   
Receiving objects:  53% (51325/96839), 30.18 MiB | 731 KiB/s   
Receiving objects:  54% (52294/96839), 30.18 MiB | 731 KiB/s   
Receiving objects:  55% (53262/96839), 30.55 MiB | 732 KiB/s   
Receiving objects:  55% (53762/96839), 30.55 MiB | 732 KiB/s   
Receiving objects:  56% (54230/96839), 30.55 MiB | 732 KiB/s   
Receiving objects:  57% (55199/96839), 30.90 MiB | 731 KiB/s   
Receiving objects:  58% (56167/96839), 31.27 MiB | 747 KiB/s   
Receiving objects:  58% (56357/96839), 31.27 MiB | 747 KiB/s   
Receiving objects:  59% (57136/96839), 31.27 MiB | 747 KiB/s   
Receiving objects:  60% (58104/96839), 31.98 MiB | 765 KiB/s   
Receiving objects:  61% (59072/96839), 31.98 MiB | 765 KiB/s   
Receiving objects:  61% (59097/96839), 31.98 MiB | 765 KiB/s   
Receiving objects:  62% (60041/96839), 32.34 MiB | 731 KiB/s   
Receiving objects:  63% (61009/96839), 32.70 MiB | 731 KiB/s   
Receiving objects:  63% (61187/96839), 32.70 MiB | 731 KiB/s   
Receiving objects:  63% (61364/96839), 33.42 MiB | 731 KiB/s   
Receiving objects:  64% (61977/96839), 33.78 MiB | 730 KiB/s   
Receiving objects:  65% (62946/96839), 34.14 MiB | 731 KiB/s   
Receiving objects:  66% (63914/96839), 34.14 MiB | 731 KiB/s   
Receiving objects:  66% (64202/96839), 34.14 MiB | 731 KiB/s   
Receiving objects:  67% (64883/96839), 34.50 MiB | 729 KiB/s   
Receiving objects:  68% (65851/96839), 34.86 MiB | 731 KiB/s   
Receiving objects:  68% (66395/96839), 34.86 MiB | 731 KiB/s   
Receiving objects:  69% (66819/96839), 34.86 MiB | 731 KiB/s   
Receiving objects:  70% (67788/96839), 35.22 MiB | 731 KiB/s   
Receiving objects:  71% (68756/96839), 35.22 MiB | 731 KiB/s   
Receiving objects:  72% (69725/96839), 35.58 MiB | 731 KiB/s   
Receiving objects:  72% (70455/96839), 35.58 MiB | 731 KiB/s   
Receiving objects:  73% (70693/96839), 35.58 MiB | 731 KiB/s   
Receiving objects:  74% (71661/96839), 35.94 MiB | 731 KiB/s   
Receiving objects:  75% (72630/96839), 36.30 MiB | 731 KiB/s   
Receiving objects:  76% (73598/96839), 36.30 MiB | 731 KiB/s   
Receiving objects:  76% (73882/96839), 36.30 MiB | 731 KiB/s   
Receiving objects:  77% (74567/96839), 36.30 MiB | 731 KiB/s   
Receiving objects:  78% (75535/96839), 36.30 MiB | 731 KiB/s   
Receiving objects:  79% (76503/96839), 36.66 MiB | 731 KiB/s   
Receiving objects:  79% (77171/96839), 36.86 MiB | 486 KiB/s   
Receiving objects:  80% (77472/96839), 36.86 MiB | 486 KiB/s   
Receiving objects:  80% (77519/96839), 37.43 MiB | 519 KiB/s   
Receiving objects:  81% (78440/96839), 37.43 MiB | 519 KiB/s   
Receiving objects:  82% (79408/96839), 37.43 MiB | 519 KiB/s   
Receiving objects:  83% (80377/96839), 38.00 MiB | 553 KiB/s   
Receiving objects:  84% (81345/96839), 38.00 MiB | 553 KiB/s   
Receiving objects:  85% (82314/96839), 38.00 MiB | 553 KiB/s   
Receiving objects:  86% (83282/96839), 38.00 MiB | 553 KiB/s   
Receiving objects:  86% (84039/96839), 38.00 MiB | 553 KiB/s   
Receiving objects:  87% (84250/96839), 38.00 MiB | 553 KiB/s   
Receiving objects:  88% (85219/96839), 38.46 MiB | 567 KiB/s   
Receiving objects:  89% (86187/96839), 38.46 MiB | 567 KiB/s   
Receiving objects:  90% (87156/96839), 38.46 MiB | 567 KiB/s   
Receiving objects:  91% (88124/96839), 38.46 MiB | 567 KiB/s   
Receiving objects:  92% (89092/96839), 38.46 MiB | 567 KiB/s   
Receiving objects:  93% (90061/96839), 38.46 MiB | 567 KiB/s   
Receiving objects:  94% (91029/96839), 38.46 MiB | 567 KiB/s   
Receiving objects:  95% (91998/96839), 38.46 MiB | 567 KiB/s   
Receiving objects:  95% (92335/96839), 40.21 MiB | 726 KiB/s   
Receiving objects:  96% (92966/96839), 40.21 MiB | 726 KiB/s   
Receiving objects:  97% (93934/96839), 40.21 MiB | 726 KiB/s   
Receiving objects:  98% (94903/96839), 40.21 MiB | 726 KiB/s   
Receiving objects:  99% (95871/96839), 40.57 MiB | 726 KiB/s   
Receiving objects:  99% (96648/96839), 40.57 MiB | 726 KiB/s   
remote: Total 96839 (delta 5), reused 31 (delta 0)[K
Receiving objects: 100% (96839/96839), 40.57 MiB | 726 KiB/s   
Receiving objects: 100% (96839/96839), 40.92 MiB | 726 KiB/s, done.
Resolving deltas:   0% (0/70554)   
Resolving deltas:   1% (733/70554)   
Resolving deltas:   2% (1419/70554)   
Resolving deltas:   3% (2142/70554)   
Resolving deltas:   4% (2826/70554)   
Resolving deltas:   5% (3633/70554)   
Resolving deltas:   6% (4249/70554)   
Resolving deltas:   7% (4953/70554)   
Resolving deltas:   8% (5645/70554)   
Resolving deltas:   9% (6351/70554)   
Resolving deltas:  10% (7096/70554)   
Resolving deltas:  11% (7763/70554)   
Resolving deltas:  12% (8467/70554)   
Resolving deltas:  13% (9176/70554)   
Resolving deltas:  14% (9882/70554)   
Resolving deltas:  15% (10603/70554)   
Resolving deltas:  16% (11402/70554)   
Resolving deltas:  17% (11998/70554)   
Resolving deltas:  18% (12712/70554)   
Resolving deltas:  19% (13471/70554)   
Resolving deltas:  20% (14138/70554)   
Resolving deltas:  21% (14871/70554)   
Resolving deltas:  22% (15647/70554)   
Resolving deltas:  23% (16228/70554)   
Resolving deltas:  24% (16960/70554)   
Resolving deltas:  25% (17667/70554)   
Resolving deltas:  26% (18345/70554)   
Resolving deltas:  27% (19052/70554)   
Resolving deltas:  28% (19812/70554)   
Resolving deltas:  29% (20501/70554)   
Resolving deltas:  30% (21176/70554)   
Resolving deltas:  31% (21987/70554)   
Resolving deltas:  32% (22580/70554)   
Resolving deltas:  33% (23294/70554)   
Resolving deltas:  33% (23382/70554)   
Resolving deltas:  34% (24000/70554)   
Resolving deltas:  35% (24710/70554)   
Resolving deltas:  36% (25401/70554)   
Resolving deltas:  37% (26164/70554)   
Resolving deltas:  38% (26850/70554)   
Resolving deltas:  39% (27534/70554)   
Resolving deltas:  40% (28335/70554)   
Resolving deltas:  41% (28930/70554)   
Resolving deltas:  42% (29658/70554)   
Resolving deltas:  43% (30413/70554)   
Resolving deltas:  44% (31135/70554)   
Resolving deltas:  45% (31771/70554)   
Resolving deltas:  46% (32606/70554)   
Resolving deltas:  47% (33161/70554)   
Resolving deltas:  48% (33900/70554)   
Resolving deltas:  49% (34606/70554)   
Resolving deltas:  50% (35584/70554)   
Resolving deltas:  51% (35995/70554)   
Resolving deltas:  52% (36722/70554)   
Resolving deltas:  53% (37424/70554)   
Resolving deltas:  54% (38114/70554)   
Resolving deltas:  55% (38818/70554)   
Resolving deltas:  56% (39520/70554)   
Resolving deltas:  57% (40365/70554)   
Resolving deltas:  58% (40989/70554)   
Resolving deltas:  59% (41627/70554)   
Resolving deltas:  60% (42338/70554)   
Resolving deltas:  61% (43121/70554)   
Resolving deltas:  62% (43760/70554)   
Resolving deltas:  63% (44511/70554)   
Resolving deltas:  64% (45200/70554)   
Resolving deltas:  65% (45893/70554)   
Resolving deltas:  66% (46639/70554)   
Resolving deltas:  67% (47309/70554)   
Resolving deltas:  68% (47977/70554)   
Resolving deltas:  69% (48719/70554)   
Resolving deltas:  70% (49705/70554)   
Resolving deltas:  71% (50186/70554)   
Resolving deltas:  72% (50856/70554)   
Resolving deltas:  73% (51523/70554)   
Resolving deltas:  74% (52218/70554)   
Resolving deltas:  75% (52926/70554)   
Resolving deltas:  76% (53639/70554)   
Resolving deltas:  77% (54331/70554)   
Resolving deltas:  78% (55034/70554)   
Resolving deltas:  79% (55856/70554)   
Resolving deltas:  80% (56467/70554)   
Resolving deltas:  81% (57261/70554)   
Resolving deltas:  82% (57856/70554)   
Resolving deltas:  83% (58565/70554)   
Resolving deltas:  84% (59374/70554)   
Resolving deltas:  85% (60114/70554)   
Resolving deltas:  85% (60197/70554)   
Resolving deltas:  86% (60690/70554)   
Resolving deltas:  87% (61405/70554)   
Resolving deltas:  88% (62100/70554)   
Resolving deltas:  89% (62803/70554)   
Resolving deltas:  90% (63504/70554)   
Resolving deltas:  91% (64205/70554)   
Resolving deltas:  92% (64928/70554)   
Resolving deltas:  93% (65618/70554)   
Resolving deltas:  94% (66606/70554)   
Resolving deltas:  95% (67108/70554)   
Resolving deltas:  96% (67737/70554)   
Resolving deltas:  97% (68654/70554)   
Resolving deltas:  98% (69148/70554)   
Resolving deltas:  99% (69958/70554)   
Resolving deltas: 100% (70554/70554)   
Resolving deltas: 100% (70554/70554), done.
/media/datos/Desarrollos/devel_example/ipython
damianavila	git@github.com:damianavila/ipython.git (fetch)
damianavila	git@github.com:damianavila/ipython.git (push)
origin	git://github.com/ipython/ipython.git (fetch)
origin	git://github.com/ipython/ipython.git (push)

NOTE: A lot of git workflows use origin to point to our fork and upstream to point to the project repo. But I do not like that configuration. It seems more natural to me to clone the project repo (the origin repo) and add a connection to my fork called damianavila... and the next steps take into consideration this last approach.

Short cycle

This short cycle just create a new branch to work on, make the needed changes in the source code and upload the local changes to our Github fork to finally submit a pull-request:

  • Set up the master and development branch names:
In [6]:
master_branch = "master"
feature_branch = "doc_post_serve"
  Click me!
  • Create a new branch from master:
In [7]:
# Make sure we are in master branch
!git checkout $master_branch

# Pull the changes from origin/master
!git pull $project_remote_name

# Start a new branch to work on
!git checkout -b $feature_branch

# Check where we are
!git status
  Click me!
Ya está en «master»
Already up-to-date.
Switched to a new branch 'doc_post_serve'
# En la rama doc_post_serve
nothing to commit, working directory clean

  • Make the changes you want to do:

NOTE: In this example, I will update the IPython docs about some details using the IPython slides and the post-serve post-processor (IPython.nbconvert).

In [9]:
# list the files structure to find the needed files
%ls
  Click me!
CONTRIBUTING.md  examples/   MANIFEST.in  setupbase.py  setup.py*
COPYING.txt      git-hooks/  README.rst   setupegg.py*  tools/
docs/            IPython/    scripts/     setupext/     tox.ini

In [10]:
%load docs/source/interactive/nbconvert.rst
# After executing %load, a new cell containing the source code will be added.
# Be sure to add the next line (with the proper path) to overwrite the file
# with you changes.
#
# %%writefile docs/source/interactive/nbconvert.rst
  Click me!
In [11]:
%%writefile docs/source/interactive/nbconvert.rst
.. _nbconvert:

Converting notebooks to other formats
=====================================

Newly added in the 1.0 release of IPython is the ``nbconvert`` tool, which 
allows you to convert an ``.ipynb`` notebook document file into various static 
formats. 

Currently, ``nbconvert`` is provided as a command line tool, run as a script 
using IPython. A direct export capability from within the 
IPython Notebook web app is planned. 

The command-line syntax to run the ``nbconvert`` script is::

  $ ipython nbconvert --to FORMAT notebook.ipynb

This will convert the IPython document file ``notebook.ipynb`` into the output 
format given by the ``FORMAT`` string.

The default output format is html, for which the ``--to`` argument may be 
omitted::
  
  $ ipython nbconvert notebook.ipynb

IPython provides a few templates for some output formats, and these can be
specified via an additional ``--template`` argument.

The currently supported export formats are:

* ``--to html``

  - ``--template full`` (default)
  
    A full static HTML render of the notebook.
    This looks very similar to the interactive view.

  - ``--template basic``
  
    Simplified HTML, useful for embedding in webpages, blogs, etc.
    This excludes HTML headers.

* ``--to latex``

  Latex export.  This generates ``NOTEBOOK_NAME.tex`` file,
  ready for export.  You can automatically run latex on it to generate a PDF
  by adding ``--post PDF``.
  
  - ``--template article`` (default)
  
    Latex article, derived from Sphinx's howto template.

  - ``--template book``
  
    Latex book, derived from Sphinx's manual template.

  - ``--template basic``
  
    Very basic latex output - mainly meant as a starting point for custom templates.

* ``--to slides``

  This generates a Reveal.js HTML slideshow.
  It must be served by an HTTP server. The easiest way to do this is adding
  ``--post serve`` on the command-line. The ``--post serve`` post-processor 
  proxies Reveal.js requests to a CDN if no local Reveal.js library is present. 
  For low connectivity environments, just place the Reveal.js library in the 
  same directory where your_talk.slides.html is located or point to another 
  directory using the ``--reveal-prefix`` alias.

* ``--to markdown``

  Simple markdown output.  Markdown cells are unaffected,
  and code cells are placed in triple-backtick (```````) blocks.

* ``--to rst``

  Basic reStructuredText output. Useful as a starting point for embedding notebooks
  in Sphinx docs.

* ``--to python``

  Convert a notebook to an executable Python script.
  This is the simplest way to get a Python script out of a notebook.
  If there were any magics in the notebook, this may only be executable from
  an IPython session.
  
.. note::

  nbconvert uses pandoc_ to convert between various markup languages,
  so pandoc is a dependency of most nbconvert transforms,
  excluding Markdown and Python.

.. _pandoc: http://johnmacfarlane.net/pandoc/

The output file created by ``nbconvert`` will have the same base name as
the notebook and will be placed in the current working directory. Any
supporting files (graphics, etc) will be placed in a new directory with the
same base name as the notebook, suffixed with ``_files``::

  $ ipython nbconvert notebook.ipynb
  $ ls
  notebook.ipynb   notebook.html    notebook_files/

For simple single-file output, such as html, markdown, etc.,
the output may be sent to standard output with::
    
  $ ipython nbconvert --to markdown notebook.ipynb --stdout
    
Multiple notebooks can be specified from the command line::
    
  $ ipython nbconvert notebook*.ipynb
  $ ipython nbconvert notebook1.ipynb notebook2.ipynb
    
or via a list in a configuration file, say ``mycfg.py``, containing the text::

  c = get_config()
  c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"]

and using the command::

  $ ipython nbconvert --config mycfg.py


.. _notebook_format:

LaTeX citations
---------------

``nbconvert`` now has support for LaTeX citations. With this capability you
can:

* Manage citations using BibTeX.
* Cite those citations in Markdown cells using HTML data attributes.
* Have ``nbconvert`` generate proper LaTeX citations and run BibTeX.

For an example of how this works, please see the citations example in
the nbconvert-examples_ repository.

.. _nbconvert-examples: https://github.com/ipython/nbconvert-examples

Notebook JSON file format
-------------------------

Notebook documents are JSON files with an ``.ipynb`` extension, formatted
as legibly as possible with minimal extra indentation and cell content broken
across lines to make them reasonably friendly to use in version-control
workflows.  You should be very careful if you ever manually edit this JSON
data, as it is extremely easy to corrupt its internal structure and make the
file impossible to load.  In general, you should consider the notebook as a
file meant only to be edited by the IPython Notebook app itself, not for 
hand-editing.

.. note::

     Binary data such as figures are also saved directly in the JSON file.  
     This provides convenient single-file portability, but means that the 
     files can be large; a ``diff`` of binary data is also not very 
     meaningful.  Since the binary blobs are encoded in a single line, they 
     affect only one line of the ``diff`` output, but they are typically very 
     long lines.  You can use the ``Cell | All Output | Clear`` menu option to 
     remove all output from a notebook prior to committing it to version 
     control, if this is a concern.

The notebook server can also generate a pure Python version of your notebook, 
using the ``File | Download as`` menu option. The resulting ``.py`` file will 
contain all the code cells from your notebook verbatim, and all Markdown cells 
prepended with a comment marker.  The separation between code and Markdown
cells is indicated with special comments and there is a header indicating the
format version.  All output is removed when exporting to Python.

As an example, consider a simple notebook called ``simple.ipynb`` which 
contains one Markdown cell, with the content ``The simplest notebook.``, one 
code input cell with the content ``print "Hello, IPython!"``, and the 
corresponding output.

The contents of the notebook document ``simple.ipynb`` is the following JSON 
container::

  {
   "metadata": {
    "name": "simple"
   },
   "nbformat": 3,
   "nbformat_minor": 0,
   "worksheets": [
    {
     "cells": [
      {
       "cell_type": "markdown",
       "metadata": {},
       "source": "The simplest notebook."
      },
      {
       "cell_type": "code",
       "collapsed": false,
       "input": "print \"Hello, IPython\"",
       "language": "python",
       "metadata": {},
       "outputs": [
        {
         "output_type": "stream",
         "stream": "stdout",
         "text": "Hello, IPython\n"
        }
       ],
       "prompt_number": 1
      }
     ],
     "metadata": {}
    }
   ]
  }


The corresponding Python script is::

  # -*- coding: utf-8 -*-
  # <nbformat>3.0</nbformat>

  # <markdowncell>

  # The simplest notebook.

  # <codecell>

  print "Hello, IPython"

Note that indeed the output of the code cell, which is present in the JSON 
container, has been removed in the ``.py`` script.
  Click me!
Overwriting docs/source/interactive/nbconvert.rst

  • Check the status and diff of your modifications:
In [12]:
# Check status
!git status
  Click me!
# En la rama doc_post_serve
# Cambios no preparados para el commit:
#   (use «git add <archivo>...» para actualizar lo que se ejecutará)
#   (use «git checkout -- <archivo>...« para descartar cambios en le directorio de trabajo)
#
#	modificado:   docs/source/interactive/nbconvert.rst
#
no hay cambios agregados al commit (use «git add» o «git commit -a»)

In [13]:
# See the diff
!git diff
  Click me!
diff --git a/docs/source/interactive/nbconvert.rst b/docs/source/interactive/nbconvert.rst
index 1789a62..610edf0 100644
--- a/docs/source/interactive/nbconvert.rst
+++ b/docs/source/interactive/nbconvert.rst
@@ -61,8 +61,12 @@ The currently supported export formats are:
 * ``--to slides``
 
   This generates a Reveal.js HTML slideshow.
-  It must be served by an HTTP server.  The easiest way to do this is adding
-  ``--post serve`` on the command-line.
+  It must be served by an HTTP server. The easiest way to do this is adding
+  ``--post serve`` on the command-line. The ``--post serve`` post-processor 
+  proxies Reveal.js requests to a CDN if no local Reveal.js library is present. 
+  For low connectivity environments, just place the Reveal.js library in the 
+  same directory where your_talk.slides.html is located or point to another 
+  directory using the ``--reveal-prefix`` alias.
 
 * ``--to markdown``
 
@@ -224,4 +228,3 @@ The corresponding Python script is::
 
 Note that indeed the output of the code cell, which is present in the JSON 
 container, has been removed in the ``.py`` script.
-

  • Add the changes an commit them:
In [14]:
# Add the modified files to the stage
!git add .
  Click me!
In [15]:
# And do your commit
!git commit -am "Added --post-serve explanation into the nbconvert docs."
  Click me!
[doc_post_serve c87ac2f] Added --post-serve explanation into the nbconvert docs.
 1 file changed, 6 insertions(+), 3 deletions(-)

  • Finally, push your local development branch to your Github fork:
In [16]:
# Push updates from your local branch to your github branch
!git push $my_fork_remote_name $feature_branch
  Click me!
Counting objects: 8732, done.
Delta compression using up to 4 threads.
Compressing objects:   0% (1/2767)   
Compressing objects:   1% (28/2767)   
Compressing objects:   2% (56/2767)   
Compressing objects:   3% (84/2767)   
Compressing objects:   4% (111/2767)   
Compressing objects:   5% (139/2767)   
Compressing objects:   6% (167/2767)   
Compressing objects:   7% (194/2767)   
Compressing objects:   8% (222/2767)   
Compressing objects:   9% (250/2767)   
Compressing objects:  10% (277/2767)   
Compressing objects:  11% (305/2767)   
Compressing objects:  12% (333/2767)   
Compressing objects:  13% (360/2767)   
Compressing objects:  14% (388/2767)   
Compressing objects:  15% (416/2767)   
Compressing objects:  16% (443/2767)   
Compressing objects:  17% (471/2767)   
Compressing objects:  18% (499/2767)   
Compressing objects:  19% (526/2767)   
Compressing objects:  20% (554/2767)   
Compressing objects:  21% (582/2767)   
Compressing objects:  22% (609/2767)   
Compressing objects:  23% (637/2767)   
Compressing objects:  24% (665/2767)   
Compressing objects:  25% (692/2767)   
Compressing objects:  26% (720/2767)   
Compressing objects:  27% (748/2767)   
Compressing objects:  28% (775/2767)   
Compressing objects:  29% (803/2767)   
Compressing objects:  30% (831/2767)   
Compressing objects:  31% (858/2767)   
Compressing objects:  32% (886/2767)   
Compressing objects:  33% (914/2767)   
Compressing objects:  34% (941/2767)   
Compressing objects:  35% (969/2767)   
Compressing objects:  36% (997/2767)   
Compressing objects:  37% (1024/2767)   
Compressing objects:  38% (1052/2767)   
Compressing objects:  39% (1080/2767)   
Compressing objects:  40% (1107/2767)   
Compressing objects:  41% (1135/2767)   
Compressing objects:  42% (1163/2767)   
Compressing objects:  43% (1190/2767)   
Compressing objects:  44% (1218/2767)   
Compressing objects:  45% (1246/2767)   
Compressing objects:  46% (1273/2767)   
Compressing objects:  47% (1301/2767)   
Compressing objects:  48% (1329/2767)   
Compressing objects:  49% (1356/2767)   
Compressing objects:  50% (1384/2767)   
Compressing objects:  51% (1412/2767)   
Compressing objects:  52% (1439/2767)   
Compressing objects:  53% (1467/2767)   
Compressing objects:  54% (1495/2767)   
Compressing objects:  55% (1522/2767)   
Compressing objects:  56% (1550/2767)   
Compressing objects:  57% (1578/2767)   
Compressing objects:  58% (1605/2767)   
Compressing objects:  59% (1633/2767)   
Compressing objects:  60% (1661/2767)   
Compressing objects:  61% (1688/2767)   
Compressing objects:  62% (1716/2767)   
Compressing objects:  63% (1744/2767)   
Compressing objects:  64% (1771/2767)   
Compressing objects:  65% (1799/2767)   
Compressing objects:  66% (1827/2767)   
Compressing objects:  67% (1854/2767)   
Compressing objects:  68% (1882/2767)   
Compressing objects:  69% (1910/2767)   
Compressing objects:  70% (1937/2767)   
Compressing objects:  71% (1965/2767)   
Compressing objects:  72% (1993/2767)   
Compressing objects:  73% (2020/2767)   
Compressing objects:  74% (2048/2767)   
Compressing objects:  75% (2076/2767)   
Compressing objects:  76% (2103/2767)   
Compressing objects:  77% (2131/2767)   
Compressing objects:  78% (2159/2767)   
Compressing objects:  79% (2186/2767)   
Compressing objects:  80% (2214/2767)   
Compressing objects:  81% (2242/2767)   
Compressing objects:  82% (2269/2767)   
Compressing objects:  83% (2297/2767)   
Compressing objects:  84% (2325/2767)   
Compressing objects:  85% (2352/2767)   
Compressing objects:  86% (2380/2767)   
Compressing objects:  87% (2408/2767)   
Compressing objects:  88% (2435/2767)   
Compressing objects:  89% (2463/2767)   
Compressing objects:  90% (2491/2767)   
Compressing objects:  91% (2518/2767)   
Compressing objects:  92% (2546/2767)   
Compressing objects:  93% (2574/2767)   
Compressing objects:  94% (2601/2767)   
Compressing objects:  95% (2629/2767)   
Compressing objects:  96% (2657/2767)   
Compressing objects:  97% (2684/2767)   
Compressing objects:  98% (2712/2767)   
Compressing objects:  99% (2740/2767)   
Compressing objects: 100% (2767/2767)   
Compressing objects: 100% (2767/2767), done.
Writing objects:   0% (1/7842)   
Writing objects:   1% (79/7842)   
Writing objects:   2% (157/7842)   
Writing objects:   3% (236/7842)   
Writing objects:   4% (314/7842)   
Writing objects:   5% (393/7842)   
Writing objects:   6% (471/7842)   
Writing objects:   7% (549/7842)   
Writing objects:   8% (628/7842)   
Writing objects:   9% (706/7842)   
Writing objects:  10% (785/7842)   
Writing objects:  11% (863/7842)   
Writing objects:  12% (942/7842)   
Writing objects:  13% (1020/7842)   
Writing objects:  14% (1099/7842)   
Writing objects:  15% (1177/7842)   
Writing objects:  16% (1255/7842)   
Writing objects:  17% (1335/7842)   
Writing objects:  18% (1415/7842)   
Writing objects:  19% (1496/7842)   
Writing objects:  20% (1570/7842)   
Writing objects:  21% (1647/7842)   
Writing objects:  22% (1727/7842)   
Writing objects:  23% (1804/7842)   
Writing objects:  24% (1883/7842)   
Writing objects:  25% (1961/7842)   
Writing objects:  26% (2041/7842)   
Writing objects:  27% (2119/7842)   
Writing objects:  28% (2198/7842)   
Writing objects:  29% (2275/7842)   
Writing objects:  30% (2358/7842)   
Writing objects:  31% (2439/7842)   
Writing objects:  32% (2510/7842)   
Writing objects:  33% (2588/7842)   
Writing objects:  34% (2669/7842)   
Writing objects:  35% (2745/7842)   
Writing objects:  36% (2825/7842)   
Writing objects:  37% (2902/7842)   
Writing objects:  38% (2980/7842)   
Writing objects:  39% (3059/7842)   
Writing objects:  40% (3137/7842)   
Writing objects:  41% (3216/7842)   
Writing objects:  42% (3294/7842)   
Writing objects:  43% (3373/7842)   
Writing objects:  44% (3451/7842)   
Writing objects:  45% (3529/7842)   
Writing objects:  46% (3608/7842)   
Writing objects:  47% (3686/7842)   
Writing objects:  48% (3765/7842)   
Writing objects:  49% (3843/7842)   
Writing objects:  50% (3921/7842)   
Writing objects:  51% (4000/7842)   
Writing objects:  52% (4079/7842)   
Writing objects:  53% (4159/7842)   
Writing objects:  54% (4235/7842)   
Writing objects:  55% (4314/7842)   
Writing objects:  56% (4392/7842)   
Writing objects:  57% (4470/7842)   
Writing objects:  58% (4549/7842)   
Writing objects:  59% (4627/7842)   
Writing objects:  60% (4706/7842)   
Writing objects:  61% (4785/7842)   
Writing objects:  62% (4863/7842)   
Writing objects:  63% (4942/7842)   
Writing objects:  64% (5019/7842)   
Writing objects:  65% (5098/7842)   
Writing objects:  66% (5176/7842)   
Writing objects:  67% (5255/7842)   
Writing objects:  68% (5333/7842)   
Writing objects:  69% (5411/7842)   
Writing objects:  70% (5490/7842)   
Writing objects:  71% (5568/7842)   
Writing objects:  72% (5647/7842)   
Writing objects:  73% (5725/7842)   
Writing objects:  74% (5804/7842)   
Writing objects:  75% (5888/7842)   
Writing objects:  76% (5960/7842)   
Writing objects:  77% (6039/7842)   
Writing objects:  78% (6117/7842)   
Writing objects:  79% (6196/7842)   
Writing objects:  80% (6274/7842)   
Writing objects:  81% (6353/7842)   
Writing objects:  82% (6431/7842)   
Writing objects:  83% (6509/7842)   
Writing objects:  84% (6588/7842)   
Writing objects:  85% (6666/7842)   
Writing objects:  86% (6745/7842)   
Writing objects:  87% (6823/7842)   
Writing objects:  88% (6903/7842)   
Writing objects:  89% (6980/7842)   
Writing objects:  90% (7058/7842)   
Writing objects:  91% (7138/7842)   
Writing objects:  92% (7215/7842)   
Writing objects:  93% (7294/7842)   
Writing objects:  94% (7373/7842)   
Writing objects:  95% (7450/7842)   
Writing objects:  96% (7529/7842)   
Writing objects:  97% (7607/7842)   
Writing objects:  98% (7686/7842)   
Writing objects:  99% (7764/7842)   
Writing objects: 100% (7842/7842)   
Writing objects: 100% (7842/7842), 1.44 MiB, done.
Total 7842 (delta 5520), reused 7275 (delta 4971)
To git@github.com:damianavila/ipython.git
 * [new branch]      doc_post_serve -> doc_post_serve

NOTE: The merging of your Github development branch into the master is done via pull-request on the Github website. For reference, you can see the proposed PR here: https://github.com/ipython/ipython/pull/4751

As you can see, this workflow is very simple... and with the aid of this ipytmpl is easier than before (before = making the same but in your traditional console).

You set up the environment, fill the variables to use a posteriori, and you have only to be concern about the changes you want to introduce (or remove) from the source code. All the other steps, all those git calls are predetermined and will be called whereas you advance in the workflow...

After making the PR at the Github website, you will receive some feedback and if you have to modified something, just start the short cycle again... Sometimes you will need more... I mean, because you are working in a communitary project, if somebody changes the same file as you, there will be some conflicts at the merge step, so it will be necessary to rebase the "thing". But this is the central idea of the second Extended cycle which I will describe you in a second part of this post.

As always, I am waiting for your comments and critics!

OK, too long... I hope you did not get bored!

Have a nice New Year! And I see you in 2014 ;-)

Cheers.

Damián

Do you like the content? Great! Then help me to achieve a "Sustainable Crowdfunding"!

Comments powered by Disqus
Contents © 2014 Damian Avila - Powered by Nikola - Zen theme based in Arusahni's website-template
Creative Commons License BY-NC-SA