=================================== ``Sphinx`` における文章作成 =================================== :program:`Sphinx` における文章作成の場合、通常のワープロのように一つの文章を一つのファイルで編集するというよりは 一つの文章をdirectory単位で行う。以下はlinuxの場合のコンパイル後の文章フォルダーのdirectory構造。 .. code-block:: . ├── build │   ├── doctrees │   │   └── nbsphinx │   ├── html │   │   ├── _sources │   │   └── _static │   └── latex └── source ├── _static └── _templates .. .. blockdiag:: blockdiag { orientation = portrait //default_fontsize = 10; root -> source ; source -> static ; source -> templates ; root -> build ; build -> latex ; build -> doctrees ; build -> html ; } そこで、最初に文章に対するdirectory等の設定を、pyhonのユーティリティソフトを用いて、 より簡便に文章を作成する方法を紹介する。 文章作成フロー --------------- templateファイルのダウンロード ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 新しい文章用の空directoryを作成し以下のテンプレートファイルをクリックしてダウンロードする。 report 用 """""""""" + 共通 * :download:`Makefile.template ` * :download:`index.rst.template ` * :download:`conf.py.template ` + ubuntu 18.04 対応 * :download:`sphinx_latexpdfja.py ` + ubuntu 20.04 対応 * :download:`sphinx_report_20.04.py ` + conda3-5.3.1 対応 * :download:`sphinx_conda3_5.3.1.py ` * :download:`conf_conda.py.template ` + ubuntu 22.04 対応 * :download:`sphinx_report_22.04.py ` * :download:`conf_22.04.py.template ` 卒論、修論用 """""""""""""" 修論、卒論作成の際はこちらのテンプレートファイルをダウンロードしてください + 共通 * :download:`Makefile.template ` * :download:`index_thesis.rst.template ` * :download:`intro.rst.template ` * :download:`M-M.rst.template ` * :download:`results.rst.template ` * :download:`2016.rst.template <2016.rst.template>` * :download:`conf_B4.py.template ` * :download:`conf_M2.py.template ` + ubuntu 18.04 対応 * :download:`sphinx_thesis.py ` + ubuntu 20.04 対応 * :download:`sphinx_thesis_20.04.py ` + conda3-5.3.1 対応 * :download:`sphinx_thesis_conda3-5.3.1.py ` * :download:`conf_B4_conda.py.template ` * :download:`conf_M2_conda.py.template ` + ubuntu 22.04 対応 * :download:`sphinx_thesis_22.04.py ` * :download:`conf_B4_22.04.py.template ` * :download:`conf_M2_22.04.py.template ` 共通ツール（図のテーブルを作成したい時(python3対応）） """"""""""""""""""""""""""""""""""""""""""""""""""""""" 図を含むテーブル作成用のツール * :download:`figures2table.py ` (Captionをつけることができる) * :download:`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は使えない 文章作成ツールの実行 ~~~~~~~~~~~~~~~~~~~~~ 作りたいディレクトリで ``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 Restructured textを編集 ~~~~~~~~~~~~~~~~~~~~~~~~~ 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% 文章生成コマンドを実行する ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 文章のルートディレクトリーで ``OpenTerminal`` をひらき、以下の出力生成のコマンドのいずれかをを走らせる。 .. code-block:: bash $ make latexpdf #pdf作成 $ make html #html作成 .. hint:: latex生成の際エラーが出て生成が止まってしまったら .. image:: halt.png :height: 250 :: ? この時は :kbd:`Ctrl-Z` で生成プロセスから抜けましょう。そして:: $ make clean してから、間違った箇所を編集します。 出力の確認 ~~~~~~~~~~ * 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生成中にエラーで止まらなくても、ディレクティブの構文エラー（特に、数式や図など）があるときは 空白になっていることがある。 windows10の場合における文章作成フロー -------------------------------------- .. warning:: windowsにおいてはいくつかの機能が使えないのであくまで下書きと心得る - :program:`actdiag` , :program:`blockdiag` は使えない - :program:`jupyter-notebook` ファイルの埋め込みもできない - :program:`sphinx` のthemeはdefaultに付随するもののみ( ``traditional`` に設定している) - :program:`geometry` , :program:`babel` も使えない windows用templateファイルのダウンロード ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 新しい文章用の空directoryを作成し以下のテンプレートファイルをクリックしてダウンロードする。 report 用 """"""""""" * :download:`make.bat <./windows/report/make.bat>` * :download:`index_org.rst <./windows/report/index_org.rst>` * :download:`conf_windows.py <./windows/report/conf_windows.py>` * :download:`sphinx_report_windows.py <./windows/report/sphinx_report_windows.py>` 以下のディレクトリ構成となる:: . └── docs ├── build ├── source ├── _templates └── _static ├── conf.py ├── index.rst └── make.bat 卒論、修論用 """""""""""" 修論、卒論作成の際はこちらのテンプレートファイルをダウンロードしてください * :download:`make.bat <./windows/thesis/make.bat>` * :download:`index_thesis_windows.rst <./windows/thesis/index_thesis_windows.rst>` * :download:`conf_B4_windows.py <./windows/thesis/conf_B4_windows.py>` * :download:`conf_M2_windows.py <./windows/thesis/conf_M2_windows.py>` * :download:`sphinx_thesis_windows.py <./windows/thesis/sphinx_thesis_windows.py>` * :download:`intro_org.rst <./windows/thesis/intro_org.rst>` * :download:`M-M_org.rst <./windows/thesis/M-M_org.rst>` * :download:`results_org.rst <./windows/thesis/results_org.rst>` * :download:`2024_org.rst <./windows/thesis/2024_org.rst>` 以下のディレクトリ構成となる:: . └── docs ├── build ├── source ├──introduction └──intro.rst ├──material_methods └──M-M.rst ├──_results └──_results.rst └──_2024 └──_2024.rst ├── _templates └── _static ├── conf.py ├── index.rst └── make.bat .. warning:: 通常は :file:`source` directoryの下に :file:`results` その下に :file:`2024` のdirectoryができるが、 - :file:`results` -> :file:`_results` - :file:`2024` -> :file:`_2024` - :file:`results.rst` -> :file:`_results.rst` - :file:`2024.rst` -> :file:`_2024.rst` という変則的な形となっている ------------------------------------------------------------ 文章作成ツールの実行 ~~~~~~~~~~~~~~~~~~~~~ windowsにおいては全て :program:`anaconda` の Powershell で行う。 スタートメニューから :menuselection:`anaconda --> Anaconda Powershell Prormpt` で Powershellは開いておく。 文章フォルダの作り方 """"""""""""""""""""""" エクスプローラーで文書を作成する空フォルダーを作成する。 .. figure:: ./windows/No4-5.jpg :width: 500 ここでは/Documents/sphinxの下にtryというフォルダーを作成している .. caution:: One driveに作成するのNG エクスプローラーから空フォルダーのアドレスをコピーする。 .. figure:: ./windows/No4-6.jpg :width: 500 赤丸の部分をクリックして **コピー** Powershellではhome directoryのままなので空フォルダーへ移動する .. code-block:: Powershell cd ペースト （ex ``cd C:\Users\yukiy\Documents\sphinx\try\`` ）を入力して **Enter** .. figure:: ./windows/No4-7.png :width: 500 ファイルを作成する文章のルートディレクトリーに移動している。 文章作成の準備 """"""""""""""" 作りたいディレクトリで ``Powershell`` を開き、以下のような操作を行うことで PCは文章作成の準備を完了する。 .. code-block:: Powershell $ python sphinx_report_windows.py 実行画面はlinuxの項を参照のこと。 Restructured textを編集 ~~~~~~~~~~~~~~~~~~~~~~~~~ :file:`source` フォルダの中の :file:`rst` ファイルを編集する。 linuxと基本同じ。 :program:`VScode` を使って編集。 文章生成コマンドを実行する ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Powershellで以下の出力生成のコマンドのいずれかを走らせる。 文章のルートディレクトリーでないといけない。 .. code-block:: Powershell .\make latexpdf #pdf作成 .\make html #html作成 .. hint:: latex生成の際エラーが出て生成が止まってしまったら .. image:: halt.png :height: 250 :: ? この時は :kbd:`Ctrl-Z` で生成プロセスから抜けましょう。何回も押さないといけない。そして:: $ .\make clean してから、間違った箇所を編集します。 出力の確認 ~~~~~~~~~~ linuxと基本同じ .. hint:: linuxで作成したsphinxの文章フォルダをwindowsで修正したい 文章フォルダのsourceのところをコピーして、make.batを文章のルートディレクトリーにおいておく。