quick_start.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 概要\n",
    "\n",
    "このドキュメントはjig-py をJupyterLab Notebook上で利用するためのクイックスタートガイドです。\n",
    "\n",
    "jig-py 自身のリポジトリを解析対象として、Jigライブラリの利用方法をお伝えします\n",
    "\n",
    "実行結果も含めて見たい場合には、[https://htmlpreview.github.io/?https://github.com/levii/jig-py/blob/master/quick_start.html](https://htmlpreview.github.io/?https://github.com/levii/jig-py/blob/master/quick_start.html) を参照してください。\n",
    "\n",
    "## 準備\n",
    "\n",
    "次の準備が整った状態を想定しています。\n",
    "\n",
    "* jig-pyとGraphvizのインストールを完了\n",
    "* jig-pyのリポジトリをダウンロードし、リポジトリのディレクトリに移動\n",
    "* JupyterLab を起動し、新規Notebookを開いた状態\n",
    "\n",
    "## 流れ\n",
    "\n",
    "* Pythonアプリケーションのモジュール依存性の可視化\n",
    "* モジュールの掘り下げ\n",
    "* モジュールの削除\n",
    "* 特定のモジュールのみにフォーカスする\n",
    "* リセット（初期状態に戻す）\n",
    "* ノードのスタイルを変更する\n",
    "* エッジのスタイルを変更する\n",
    "* スタイルをリセットする\n",
    "* 自動ハイライト（試験的な機能）\n",
    "\n",
    "では、早速見ていきましょう。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 解析の開始\n",
    "\n",
    "Jigクラスをインポートし、`analyze_module_dependency()` メソッドに解析対象のアプリケーションのルートディレクトリを指定してグラフコントローラーオブジェクトを取得します。\n",
    "\n",
    "アプリケーション内の任意のディレクトリを指定することはできないので注意してください（解析がうまくいかずエラーになるなど正しい挙動で動きません）。\n",
    "\n",
    "取得したオブジェクトを直接Notebook上で評価するとモジュールの依存グラフが表示されます。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ji-pyリポジトリのルートにいる前提なので、カレントディレクトリを指定\n",
    "\n",
    "from jig import Jig\n",
    "g = Jig.analyze_module_dependency(\".\")\n",
    "g"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## グラフ表示について\n",
    "\n",
    "ノードがモジュールを表し、矢印がモジュール同士の依存関係を示しています。\n",
    "`tests -> jig` は `tests` モジュール（パッケージ）が `jig` に依存していることを表します。\n",
    "\n",
    "また、ノードの形によってそれ以上掘り下げるかどうかが分かります。\n",
    "ノードの形が四角い場合は、掘り下げが可能です。掘り下げできない場合は楕円で表示されます。\n",
    "\n",
    "## モジュールの掘り下げ\n",
    "\n",
    "モジュール（ノード）を掘り下げるには `dig()` メソッドに掘り下げたいモジュール名を指定します。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.dig(\"jig\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "複数同時に掘り下げることもできます。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.dig(\"tests\", \"build\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## モジュールの削除\n",
    "\n",
    "削除したい場合は `remove()` にモジュール名を指定して呼び出します（複数指定可能）。\n",
    "\n",
    "掘り下げたモジュールの名前を指定して、その内部にあるモジュールごとまとめて削除することもできます。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.remove(\"build.lib\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.remove(\"tests\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 特定のモジュールのみにフォーカスする\n",
    "\n",
    "特定のモジュールのみにフォーカスしてみたい場合は、 `focus()` を利用します。\n",
    "\n",
    "任意の数のモジュール名を指定できます。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.focus(\"jig.cli\", \"jig.collector\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## リセット（初期状態に戻す）\n",
    "\n",
    "解析を最初からやり直したい場合は `reset()` で最初の状態に戻すことができます。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.reset()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.dig(\"jig\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ノードのスタイル指定\n",
    "\n",
    "ノードのスタイルを変更するには `style()` を利用します。\n",
    "\n",
    "スタイルは `color`, `fontcolor`, `penwidth` が指定できます。\n",
    "\n",
    "`color` および `fontcolor` には以下の値が設定できます。\n",
    "\n",
    "* \"white\"\n",
    "* \"black\"\n",
    "* \"darkgray\"\n",
    "* \"lightgray\"\n",
    "* \"red\"\n",
    "* \"blue\"\n",
    "* \"green\"\n",
    "* \"yellow\"\n",
    "* \"purple\"\n",
    "* \"teal\"\n",
    "* \"navy\"\n",
    "\n",
    "`penwidth` には以下の値が設定できます。\n",
    "\n",
    "* \"normal\"\n",
    "* \"bold\"\n",
    "* \"thin\"\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.style(\"jig.visualizer\", color=\"red\", fontcolor=\"green\", penwidth=\"bold\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## エッジのスタイルを変更する\n",
    "\n",
    "`edge_style()` を呼ぶことで特定のモジュールをつなぐエッジのスタイルを変更できます。\n",
    "\n",
    "スタイルは `color` と `penwidth` を指定することができます。\n",
    "\n",
    "指定できる値については `style()` で指定できるものと同じです。\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.edge_style(\"tests\", \"jig\", color=\"blue\", penwidth=\"thin\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## スタイルのリセット\n",
    "\n",
    "設定したスタイルを元に戻したい場合は、 `reset_style()` で戻すことができます。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.reset_style()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 自動ハイライト機能\n",
    "\n",
    "試験的な機能として自動ハイライト機能があります。\n",
    "\n",
    "以下の条件を検出して、自動でノードおよびエッジのスタイルを設定します。\n",
    "\n",
    "* 相互参照しているモジュールのエッジ\n",
    "* 参照しかしていないモジュール（自分に向いている矢印がない）\n",
    "* 依存しかされていないモジュール（自分から出て行く矢印がない）\n",
    "\n",
    "実行するには `auto_highlight()` を呼び出します。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.auto_highlight()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# おつかれさまでした！\n",
    "\n",
    "クイックスタートガイドは以上になります。\n",
    "\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.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}