.. 報告会0526 documentation master file, created by
   sphinx-quickstart on Fri May 19 15:30:11 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.


=======================
具体的な文章作成の例
=======================

:program:`Sphinx` での文章ファイルは単なるテキストファイルであるが、様々なルールの
下で記述されていると文章の修飾を行うことができる。この文章フォーマットを
``Restructured text``  と呼ばれる。


文章のレベル
~~~~~~~~~~~~

文章の見出しのレベルは下記のように罫線を挿入することで分けることができる.

サンプル :: 
 
    ===========
    レベル1
    ===========
     
    レベル2
    -----------
    
    レベル3
    ~~~~~~~~~~~
    
    レベル4
    ===========
    


.. image:: level.png
   :scale: 50



実際には上のようになります。


ディレクティブについて
~~~~~~~~~~~~~~~~~~~~~~

テーブルや図、数式を入れたり、重要点などを強調するような文章を修飾する
機能は下記で示すディレクティブと呼ばれる記述方法を用いる。

ディレクティブの書き方 ::
     
    +-------+---------------------------------------------------+
    | ".. " | ディレクティブタイプ "::" ディレクティブブロック  |
    +-------+                                                   |
            |                                                   |
            +---------------------------------------------------+

ブロック図などもディレクティブを用いれば挿入することができる。


.. blockdiag::
   
    blockdiag {
    // orientation = portrait
        'A' -> 'B' -> 'C';
    }
    
例えば上のような図を挿入する場合、 :: 

    .. blockdiag::
    
       blockdiag {
         // orientation = portrait
       'A' -> 'B' -> 'C';
       }
    

縦方向にする場合は縦方向にする場合は　``//orientation = portrait`` を外す。

似たようなことは ``graphviz`` でもできる。

.. graphviz::

    digraph graph_name {
    
     graph [rankdir = LR];

     "不活性" -> "活性" [
        label = "可逆",            //エッジラベル
        taillabel = "解離",       //エッジの始端にラベルをつける
        headlabel = "会合",
        dir = both,               //エッジの矢印を指定する
       ];
    }
    
これは、::

    .. graphviz::

        digraph graph_name {
        
        graph [rankdir = LR];           //　横方向へ展開

        "不活性" -> "活性" [
            label = "可逆",            //エッジラベル
            taillabel = "解離",       //エッジの始端にラベルをつける
            headlabel = "会合",
            dir = both,               //エッジの矢印を指定する
        ];
        }

で書ける。 ``graphviz`` では縦方向がデフォルトで横方向にする場合は、 ::

    graph [rankdir = LR];

を入れている。

.. _p_toctree:

.. toctree::
   :maxdepth: 2
   
   ./graphviz/graphviz
   ./UML/UML
   ./algorithm/algorithm


ディレクティブでは、ソースコードを読み込んで表示することも可能である。

.. important:: 

   ディレクティブなどを使用する際、間違った文章を入力すると（多くはインテンドや改行が多い）エラーコードは出力されない。
   エラー部分は単に抜けてしまうので、最終出力と ``Restructured text`` の中身が一致していることを常に確認する。

toctree
~~~~~~~~

:command:`toctree` とは複数のファイルをひとつのドキュメントにまとめられる機能である。
長い文章や複数の人間で文章を仕上げる時には有効である。

.. blockdiag:: 
      
   blockdiag {
     orientation = portrait
     "index" [shape = note];
     "file1" [shape = note];
     "file2" [shape = note];
     "index" -> "file1" [dir = none];
     "index" -> "file2" [dir = none];
     
   }
   
indexの中身

例

::

    .. toctree::
       :numbered:

       goto
       tsuka

これを実行すると二人のファイルが合体しひとつのドキュメントになる。 ``:numbered:`` によって章、節などが自動的にナンバリングされる。
:command:`jupyter-notebook` との連携をセットアップしておけば、 :command:`toctree` の下に:file:`*.ipynb` を入れることも可能。
その際は拡張子は記述しない。