posts/bidirectional-ipython-nikola-workflow-to-write-your-blog-post.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The idea of this blog post is to show you how you can achieve an efficient *bidirectional* workflow to write your blog posts using great tools/features derived from **IPython** and **Nikola**.\n",
    "\n",
    "Probably, this would be interesting not only for the people using **IPython** and **Nikola** to write their blog post, but also to other people because this would be a simple but nice example of how you can integrate this two applications to better suit your needs.\n",
    "\n",
    "OK, first of all, let's go to the folder containing my blog:\n",
    "<!-- TEASER_END -->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "    damian@damian-S400CA:~$ cd /media/datos/Desarrollos/damian_blog\n",
    "    \n",
    "    damian@damian-S400CA:/media/datos/Desarrollos/damian_blog$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then I activate my **virtualenv** specifically filled to build my blog:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "    damian@damian-S400CA:/media/datos/Desarrollos/damian_blog$ workon blog\n",
    "    \n",
    "    (blog)damian@damian-S400CA:/media/datos/Desarrollos/damian_blog$ "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we are ready to the next step, calling the `nikola console`:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "    (blog)damian@damian-S400CA:/media/datos/Desarrollos/damian_blog$ nikola console\n",
    "    Scanning posts......done!\n",
    "    Python 2.7.4 (default, Apr 19 2013, 18:28:01) \n",
    "    Type \"copyright\", \"credits\" or \"license\" for more information.\n",
    "\n",
    "    IPython 1.1.0 -- An enhanced Interactive Python.\n",
    "    ?         -> Introduction and overview of IPython's features.\n",
    "    %quickref -> Quick reference.\n",
    "    help      -> Python's own help system.\n",
    "    object?   -> Details about 'object', use 'object??' for extra details.\n",
    "\n",
    "\n",
    "    Nikola v6.1.1 -- IPython Console (conf = configuration, SITE = site engine)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Yes... **Nikola** offers a feature called `nikola console` which immediately opens an **IPython** console (if you have installed IPython, of course) where you can do a lot of things, as I will show you later, but also have direct access to **Nikola** internals through the `conf` (configuration) and `SITE` (site engine) objects. We can explore this objects using the *tab completion* from the IPython machinery:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "    In [1]: conf.<TAB>\n",
    "    conf.BLOG_AUTHOR             conf.LICENSE\n",
    "    conf.BLOG_DESCRIPTION        conf.MATHJAX_CONFIG\n",
    "    conf.BLOG_EMAIL              conf.NAVIGATION_LINKS\n",
    "    conf.BLOG_TITLE              conf.PAGES\n",
    "    conf.BODY_END                conf.POSTS\n",
    "    conf.COMMENT_SYSTEM_ID       conf.py\n",
    "    conf.COMPILERS               conf.pyc\n",
    "    conf.CONTENT_FOOTER          conf.SITE_URL\n",
    "    conf.CREATE_MONTHLY_ARCHIVE  conf.SOCIAL_BUTTONS_CODE\n",
    "    conf.DEFAULT_LANG            conf.THEME\n",
    "    conf.DEPLOY_COMMANDS         conf.time\n",
    "    conf.GLOBAL_CONTEXT          conf.TRANSLATIONS\n",
    "    conf.INDEX_TEASERS           conf.unicode_literals\n",
    "    conf.IPYNB_CONFIG "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "    In [1]: SITE.<TAB>\n",
    "    SITE.abs_link                    SITE.MESSAGES\n",
    "    SITE.clean_task_paths            SITE.pages\n",
    "    SITE.commands                    SITE.path\n",
    "    SITE.compilers                   SITE.plugin_manager\n",
    "    SITE.config                      SITE.post_per_file\n",
    "    SITE.configured                  SITE.posts_per_category\n",
    "    SITE.current_lang                SITE.posts_per_month\n",
    "    SITE.default_lang                SITE.posts_per_tag\n",
    "    SITE.EXTRA_PLUGINS               SITE.posts_per_year\n",
    "    SITE.file_exists                 SITE.rel_link\n",
    "    SITE.generic_page_renderer       SITE.render_template\n",
    "    SITE.generic_post_list_renderer  SITE.scan_posts\n",
    "    SITE.gen_tasks                   SITE.strict\n",
    "    SITE.get_compiler                SITE.template_system\n",
    "    SITE.GLOBAL_CONTEXT              SITE.THEMES\n",
    "    SITE.global_data                 SITE.timeline\n",
    "    SITE.inverse_compilers           SITE.translations\n",
    "    SITE.link "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But, we will probably go back to these objects in another blog post... now, we go again to the **Nikola IPython** console because we want to create a new post. The easiest way to do it is just calling the proper **Nikola** command using the `!` to pass it from the **Nikola IPython** console to the shell.\n",
    "\n",
    "    In [1]: !nikola new_post -f ipynb\n",
    "    \n",
    "But we can do it better ;-) \n",
    "We can pass arguments to the `nikola new_post` command such as the `title`, `tags`, `format` (we have already pass the format with `-f ipynb`), etc. So, let me create some variables for these arguments inside my **Nikola IPython** console session:\n",
    "\n",
    "    In [1]: title = \"Bidirectional IPython-Nikola workflow to write your blog post\"\n",
    "    \n",
    "    In [2]: tags_list = ['python', 'IPython', 'nikola', 'blog', 'extension', 'gh-pages', 'git', 'workflow']\n",
    "    \n",
    "    In [3]: tags = ', '.join(tags_list)\n",
    "    \n",
    "    In [4]: tags\n",
    "    Out[4]: u'python, IPython, nikola, blog, extension, gh-pages, git, workflow'\n",
    "\n",
    "Here I have the string `title` containing the title for the current blog post and a list called `tags_list` containing the corresponding tags. Later I call the `.join` method because I will need to pass a string with the tags sepatarated by commas to the `nikola new_post` command.\n",
    "\n",
    "But, **wait a minute**... I have **Python** variables containing the title and the tags for my blog post. How can pass this variables to the shell to use them as arguments of the `nikola new_post` command???\n",
    "\n",
    "OK, to solve this problem we will use an exciting feature from **IPython**, just see the following line:\n",
    "\n",
    "    In [5]: !nikola new_post -f ipynb -t \"{title}\" --tags=\"{tags}\"\n",
    "\n",
    "which will create the desired `ipynb` and the corresponding `.meta` file containing the title and tags.\n",
    "\n",
    "    Creating New Post\n",
    "    -----------------\n",
    "    \n",
    "    Title: Bidirectional IPython-Nikola workflow to write your blog post\n",
    "    Scanning posts......done!\n",
    "    Your post's metadata is at:  posts/bidirectional-ipython-nikola-workflow-to-write-your-blog-post.meta\n",
    "    [2013-10-15T19:21:28Z] NOTICE: new_post: Your post's text is at: posts/bidirectional-ipython-nikola-workflow-to-write-your-blog-post.ipynb\n",
    "\n",
    "*Que me contusi!* (or... do you see the bidirectional nature of this interaction? Nice, don't you think?)\n",
    "\n",
    "Yes, inside **IPython**, we can use the braces to pass **Python** variables to the shell... ;-) \n",
    "\n",
    "*Do you see the possibilities we have with this little feature?*\n",
    "\n",
    "Now, I *cd* into the post folder of my site and open the **IPython notebook** with my custom extensions.\n",
    "\n",
    "    In [6]: cd posts/\n",
    "    /media/datos/Desarrollos/damian_blog/posts\n",
    "    \n",
    "    In [7]: !ipython notebook --profile=myext\n",
    "\n",
    "In the **IPython Dashboard**, I will open the new `ipynb` called `bidirectional-ipython-nikola-workflow-to-write-your-blog-post.ipynb` and write the content (I am writing right now).\n",
    "\n",
    "Then, when I am done with the blog post, I need to deploy my new content to somewhere to make available to the public...\n",
    "\n",
    "And this is very easy...\n",
    "\n",
    "First, **Nikola** have a `nikola deploy` command which you can customize with your conf.py file. You can see it here my configuration:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "# Commands to execute to deploy. Can be anything, for example,\r\n",
      "# you may use rsync:\r\n",
      "# \"rsync -rav output/* joe@my.site:/srv/www/site\"\r\n",
      "# And then do a backup, or ping pingomatic.\r\n",
      "# To do manual deployment, set it to []\r\n",
      "DEPLOY_COMMANDS = [\"git add .\",\r\n",
      "                   \"git commit -am 'Update'\",\r\n",
      "                   \"git push origin master\",\r\n",
      "                   \"git subtree split --prefix output -b gh-pages\",\r\n",
      "                   \"git push -f origin gh-pages:gh-pages\",\r\n",
      "                   \"git branch -D gh-pages\"]\r\n",
      "\r\n"
     ]
    }
   ],
   "source": [
    "!sed -n 197,208p conf.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The instructions are very easy to understand, if you need more details just read this [post](../posts/one-line-deployment-of-your-site-to-gh-pages.html) I wrote some weeks ago.\n",
    "\n",
    "I am essentially pushing the content to master, creating a split and deploy it later to **gh-pages**.\n",
    "\n",
    "OK, but because I am *lazy* ;-), some weeks ago I wrote an **IPython** *javascript* extension which let me execute this `nikola deploy` command from a button in the **IPython notebook toolbar**. Essentially something like this (don't worry, I will release the extension soon):\n",
    "\n",
    "    function nikolaDeploy(path, clean) {\n",
    "      IPython.notebook.kernel.execute('cd ' + path);\n",
    "      if (clean==\"True\") {\n",
    "        IPython.notebook.kernel.execute('!nikola clean');\n",
    "      }else{\n",
    "      //do nothing\n",
    "      }\n",
    "      IPython.notebook.kernel.execute('!nikola build');\n",
    "      IPython.notebook.kernel.execute('!nikola deploy');\n",
    "      messager();\n",
    "    }\n",
    "\n",
    "As you can see, I call `nikola clean` to clean my site, the I built it with `nikola build`, and deploy it with my customized `nikola deploy`... and all these actions with just a click!\n",
    "\n",
    "And now you have the complete workflow! A very simple one, because you can make a lot of modifications to improve it. However, this workflow show you how you can integrate two exciting projects, communicate one with the other and viceversa, and get beautiful results.\n",
    "\n",
    "Hope you enjoy it!\n",
    "\n",
    "Damián."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}