===================================
``Sphinx`` における文章作成
===================================

:program:`Sphinx` における文章作成の場合、通常のワープロのように一つの文章を一つのファイルで編集するというよりは
一つの文章をdirectory単位で行う。以下はコンパイル後の文章フォルダーのdirectory構造。

.. blockdiag::

   blockdiag {
    orientation = portrait
    //default_fontsize = 10;
    
    root -> source ;
    source -> static ;
    source -> templates ;    
    root -> build ;
    build -> latex ;
    build -> doctrees ;
    build -> html ;
    
   }

そこで、最初に文章に対するdirectory等の設定を、pyhonのユーティリティソフトを用いて、
より簡便に文章を作成する方法を紹介する。

文章作成フロー
---------------


1. 新しい文章用の空directoryを作成し以下のテンプレートファイルをクリックしてダウンロードする。

   - report 用

    + 共通
        * :download:`Makefile.template <Makefile.template>`  
        * :download:`index.rst.template <index.rst.template>`  
        * :download:`conf.py.template <conf.py.template>`  
    + ubuntu 18.04 対応
        * :download:`sphinx_latexpdfja.py <sphinx_latexpdfja.py>`  
    + ubuntu 20.04 対応
        * :download:`sphinx_report_20.04.py <sphinx_report_20.04.py>`
    + conda3-5.3.1 対応
        * :download:`sphinx_conda3_5.3.1.py <sphinx_report_conda3-5.3.1.py>`
        * :download:`conf_conda.py.template <conf_conda.py.template>`      
    + ubuntu 22.04 対応
        * :download:`sphinx_report_22.04.py <sphinx_report_22.04.py>`
        * :download:`conf_22.04.py.template <conf_22.04.py.template>`

------------------------------------------
   
   修論、卒論作成の際はこちらのテンプレートファイルをダウンロードしてください
   
   - 卒論、修論用

    + 共通
        * :download:`Makefile.template <Makefile.template>`  
        * :download:`index_thesis.rst.template <index_thesis.rst.template>`  
        * :download:`intro.rst.template <intro.rst.template>`   
        * :download:`M-M.rst.template <M-M.rst.template>`   
        * :download:`results.rst.template <results.rst.template>`   
        * :download:`2016.rst.template <2016.rst.template>`   
        * :download:`conf_B4.py.template <conf_B4.py.template>`  
        * :download:`conf_M2.py.template <conf_M2.py.template>`          
    + ubuntu 18.04 対応
        * :download:`sphinx_thesis.py <sphinx_thesis.py>`
    + ubuntu 20.04 対応
        * :download:`sphinx_thesis_20.04.py <sphinx_thesis_20.04.py>`
    + conda3-5.3.1 対応
        * :download:`sphinx_thesis_conda3-5.3.1.py <sphinx_thesis_conda3-5.3.1.py>`
        * :download:`conf_B4_conda.py.template <conf_B4_conda.py.template>`  
        * :download:`conf_M2_conda.py.template <conf_M2_conda.py.template>`  
    + ubuntu 22.04 対応
        * :download:`sphinx_thesis_22.04.py <sphinx_thesis_22.04.py>`
        * :download:`conf_B4_22.04.py.template <conf_B4_22.04.py.template>`
        * :download:`conf_M2_22.04.py.template <conf_M2_22.04.py.template>`

    
   操作方法は下と同じです
   
   図のテーブルを作成したい時(python3対応）
   
   * :download:`figures2table.py <figures2table.py>`  (Captionをつけることができる)
   * :download:`images2table.py <images2table.py>`   (文中の図などはこちらが便利)
   
-------------------------------------------

.. note:: conda3-5.3.1での注意点
        
        conda3-5.3.1で行うときは、予め::
            
            $ conda install recommonmark
            $ conda install nbsphinx -c conda-forge
            $ conda install sphinx_rtd_theme
            
        でパッケージをインストールしておく。なお、actdiagとblockdiagは使えない

2. 作りたいディレクトリで ``OpenTerminal`` を開き、以下のような操作を行うことで
   PCは文章作成の準備を完了する。
   
    .. code-block:: bash
    
        $ python3 sphinx_report_20.04.py
   
   （以下は実行画面）

    .. graphviz:: 
        :caption: :program:`sphinx_report_20.04.py` の実行画面

        digraph graph_name {
        
        node [shape=none,color="transparent"]d1 d2 d3;
                   
        d1 [image="s-1.png",label=""]
        
        d2 [image="s-2.png",label=""];
        
        d3 [image="s-3.png",label=""];


        d1 -> d2 [label="タイトルと作成者を入力する"];
        
        d2 -> d3 [label="Sphinx準備をクリックする"];

        }


.. raw:: latex

    \clearpage

3.  Restructured textを編集する。
    
    .. actdiag::
        :scale: 70%
        :caption: 文章作成の概略

        {
        Editstart -> restructured -> convert -> image -> check -> Yes -> output;
        check -> No -> restructured;


        lane user {
            label = "User"
            Editstart [shape = beginpoint];
            restructured [shape = flowchart.input];
            No [shape = minidiamond];
            check [shape = flowchart.condition];
            Yes [shape = minidiamond];
            output [shape = endpoint];
                    }
        lane PC {
            convert [label = "tex"];
            image [label = "pdf"];
                        }
        restructured -> convert [label = "command"];
        convert -> image [label = "latex"];
        }
        
    ここでは、 ``source`` の下の :file:`index.rst` を右
    クリックしてeditorで開く。

    .. image:: s-6.png
        :scale: 50%
        
4.  文章のルートディレクトリーで ``OpenTerminal`` をひらき、以下の出力生成のコマンドのいずれかをを走らせる。

    .. code-block:: bash
    
        $ make latexpdf   #pdf作成
        
        $ make html       #html作成
        

5.  latex生成の際エラーが出て生成が止まってしまったら    

    .. image:: halt.png
        :height: 250

    ::
    
        ?
    この時は :kbd:`Ctrl-Z` で生成プロセスから抜けましょう。そして::
    
        $ make clean
        
    してから、間違った箇所を編集します。
    

6.  出力を確認する。

    * Latexの場合
    
      buildファイルの中のlatexの下にpdfのファイルができ生成されたものが入っている。
      
      .. image:: s-5.png
            :height: 300
            
    * htmlの場合
    
      buildの下にhtmlに :file:`index.html` があるのでブラウザーで開く
      
      .. image:: s-5-2.png
            :height: 300
            
.. warning:: 

   latex生成中にエラーで止まらなくても、ディレクティブの構文エラー（特に、数式や図など）があるときは
   空白になっていることがある。