2. Sphinx における文章作成

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

.
├── build
│   ├── doctrees
│   │   └── nbsphinx
│   ├── html
│   │   ├── _sources
│   │   └── _static
│   └── latex
└── source
    ├── _static
    └── _templates

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

2.1. 文章作成フロー

2.1.1. templateファイルのダウンロード

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

2.1.1.1. report 用

• 共通

  • Makefile.template

  • index.rst.template

  • conf.py.template

• ubuntu 18.04 対応

  • sphinx_latexpdfja.py

• ubuntu 20.04 対応

  • sphinx_report_20.04.py

• conda3-5.3.1 対応

  • sphinx_conda3_5.3.1.py

  • conf_conda.py.template

• ubuntu 22.04 対応

  • sphinx_report_22.04.py

  • conf_22.04.py.template

2.1.1.2. 卒論、修論用

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

• 共通

  • Makefile.template

  • index_thesis.rst.template

  • intro.rst.template

  • M-M.rst.template

  • results.rst.template

  • 2016.rst.template

  • conf_B4.py.template

  • conf_M2.py.template

• ubuntu 18.04 対応

  • sphinx_thesis.py

• ubuntu 20.04 対応

  • sphinx_thesis_20.04.py

• conda3-5.3.1 対応

  • sphinx_thesis_conda3-5.3.1.py

  • conf_B4_conda.py.template

  • conf_M2_conda.py.template

• ubuntu 22.04 対応

  • sphinx_thesis_22.04.py

  • conf_B4_22.04.py.template

  • conf_M2_22.04.py.template

2.1.1.3. 共通ツール（図のテーブルを作成したい時(python3対応））

図を含むテーブル作成用のツール

• figures2table.py (Captionをつけることができる)

• images2table.py (文中の図などはこちらが便利)

注釈

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.1.2. 文章作成ツールの実行

作りたいディレクトリで OpenTerminal を開き、以下のような操作を行うことで PCは文章作成の準備を完了する。

$ python3 sphinx_report_20.04.py

（以下は実行画面）

図 2.1 sphinx_report_20.04.py の実行画面

2.1.3. Restructured textを編集

Restructured textを編集する。

図 2.2 文章作成の概略

ここでは、 source の下の index.rst を右 クリックしてeditorで開く。

2.1.4. 文章生成コマンドを実行する

文章のルートディレクトリーで OpenTerminal をひらき、以下の出力生成のコマンドのいずれかをを走らせる。

$ make latexpdf   #pdf作成

$ make html       #html作成

ヒント

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

?

この時は Ctrl-Z で生成プロセスから抜けましょう。そして:

$ make clean

してから、間違った箇所を編集します。

2.1.5. 出力の確認

• Latexの場合

  buildファイルの中のlatexの下にpdfのファイルができ生成されたものが入っている。

  

• htmlの場合

  buildの下にhtmlに index.html があるのでブラウザーで開く

  

警告

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

2.2. windows10の場合における文章作成フロー

警告

windowsにおいてはいくつかの機能が使えないのであくまで下書きと心得る

• actdiag , blockdiag は使えない

• jupyter-notebook ファイルの埋め込みもできない

• sphinx のthemeはdefaultに付随するもののみ( traditional に設定している)

• geometry , babel も使えない

2.2.1. windows用templateファイルのダウンロード

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

2.2.1.1. report 用

• make.bat

• index_org.rst

• conf_windows.py

• sphinx_report_windows.py

以下のディレクトリ構成となる:

.
└── docs
    ├── build
    ├── source
        ├── _templates
        └── _static
    ├── conf.py
    ├── index.rst
    └── make.bat

2.2.1.2. 卒論、修論用

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

• make.bat

• index_thesis_windows.rst

• conf_B4_windows.py

• conf_M2_windows.py

• sphinx_thesis_windows.py

• intro_org.rst

• M-M_org.rst

• results_org.rst

• 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
  

  警告

  通常は source directoryの下に results その下に 2024 のdirectoryができるが、

  • results -> _results

  • 2024 -> _2024

  • results.rst -> _results.rst

  • 2024.rst -> _2024.rst

  という変則的な形となっている

---

2.2.2. 文章作成ツールの実行

windowsにおいては全て anaconda の Powershell で行う。 スタートメニューから anaconda ‣ Anaconda Powershell Prormpt で Powershellは開いておく。

2.2.2.1. 文章フォルダの作り方

エクスプローラーで文書を作成する空フォルダーを作成する。

図 2.3 ここでは/Documents/sphinxの下にtryというフォルダーを作成している

注意

One driveに作成するのNG

エクスプローラーから空フォルダーのアドレスをコピーする。

図 2.4 赤丸の部分をクリックして コピー

Powershellではhome directoryのままなので空フォルダーへ移動する

cd ペースト

（ex cd C:\Users\yukiy\Documents\sphinx\try\ ）を入力して Enter

ファイルを作成する文章のルートディレクトリーに移動している。

2.2.2.2. 文章作成の準備

作りたいディレクトリで Powershell を開き、以下のような操作を行うことで PCは文章作成の準備を完了する。

$ python sphinx_report_windows.py

実行画面はlinuxの項を参照のこと。

2.2.3. Restructured textを編集

source フォルダの中の rst ファイルを編集する。

linuxと基本同じ。

VScode を使って編集。

2.2.4. 文章生成コマンドを実行する

Powershellで以下の出力生成のコマンドのいずれかを走らせる。 文章のルートディレクトリーでないといけない。

.\make latexpdf   #pdf作成

.\make html       #html作成

ヒント

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

?

この時は Ctrl-Z で生成プロセスから抜けましょう。何回も押さないといけない。そして:

$ .\make clean

してから、間違った箇所を編集します。

2.2.5. 出力の確認

linuxと基本同じ

ヒント

linuxで作成したsphinxの文章フォルダをwindowsで修正したい

文章フォルダのsourceのところをコピーして、make.batを文章のルートディレクトリーにおいておく。