Python
GitHub
Eclipse
Sphinx

Sphinx+Eclipse環境構築メモ

こっちのほうが読みやすいかも↓
https://markinada.github.io/DocSphinxHowTo/

Sphinx+Eclipse環境構築メモ

Sphinx+Eclipse環境で快適なドキュメントワークを実現する。

作成日: 2018/07/17

はじめに

Windows 7 64bit環境にて作業を行うが、LinuxでもMacでもそんなに変わらないはず。

以下、手順概要

  Pythonインスコ -> Sphinxインスコ -> Eclipseインスコ -> Eclipse設定 -> Document作成;

1. Pythonのインストール

Sphinxをインストールする前にPythonのインストールが必要。すでにインストール済みの場合は作業の必要なし。
公式のPythonインストーラを使うより、Pythonディストリビューションの"Anaconda"を使うことをおすすめする。
Anacondaだとデータサイエンス系に必要なライブラリもまとめてインストールすることが可能。
後になってAnacondaにしておけば!となったときに面倒なため最初からAnacondaにする。
とにかく、AnacondaでPython環境を入れよう。https://www.anaconda.com/download/#windows

★注意!:Anacondaをインストールするとき、PATH(環境変数)を自動的に追加するチェックボックスは忘れなくチェックしておく。その他はデフォルトのままで問題ない。

インストールが完了したら、pythonがちゃんとインスコされているかバージョンを確認してみる。

   $python -V
   Python 3.6.5 :: Anaconda, Inc.

2. Sphinxのインストール

Pythonがインストールできたら、次はSphinxをインストールする。Pythonのpipコマンドでインストール。
環境変数にはAnacondaインスコ時に自動的に追加されているはずなので、コマンドプロンプトに直接入力。

   $pip install sphinx Pillow

ちゃんとインストール完了できたかバージョンを見てみる。

   $sphinx-quickstart --version
   sphinx-quickstart 1.7.4

では早速ドキュメントのプロジェクトを作ってみる。quickstartの詳細説明(http://sphinx-users.jp/gettingstarted/sphinxquickstart.html)

   $sphinx-quickstart %USERPROFILE%\SphinxProjects\SampleDoc

quickstart1.PNGquickstart2.PNG

上記実行すると色々と質問されるが、Project NameとAuthor Name以外はEnterキーでスキップしてOK。これでユーザープロファイル下にSphinxProjectsディレクトリをつくり、その中にプロジェクト"SampleDoc"の作成が完了。

Projects.PNG

3. Eclipseのインストール

この時点で、テキストエディタとコマンドプロンプトでSphinxのドキュメント作成を行うことは可能。
しかし、もう少し我慢して一手間かけて統合開発環境 Eclipseで快適な環境にしよう。
Eclipseのインストールして初期設定までは行おう⇒手順リンク(https://markinada.github.io/DocEclipseHowTo/)

4. Eclipseの設定

まずは必要なプラグインが2つあるのでインストールする。

4-1. ReST Editor

Help -> Eclipse Marketplaceから"ReST Editor"を検索し、インストールする。

ReSTEditor.PNG

4-2. PyDev

Help -> Eclipse Marketplaceから"PyDev"を検索し、インストールする。

PyDev.PNG

4-3. Pythonライブラリロード

インストールが終わったらPythonのライブラリをEclipseにロードさせる。Window -> Preferences -> PyDev -> Interpreters -> Python Interpreter。

PythonLoad.PNG

5. Buildしてhtml生成

5-1. Sphinxプロジェクトの読み込み

File -> New -> Other から、以下のようにプロジェクトを読み込む

New1.PNG

New2.PNG

New3.PNG

最後にconf.pyとindex.rstをsourceディレクトリ内に移動し、上書きする。
※注意!! すでにsourceディレクトリにconf.pyとindex.rstがある状態で読み込みをこれらが初期化されてしまいます!

ChangeSouce.PNG

5-2. ビルド設定

Run -> Run Configurationsを開き、"Sphinx (via make file)"から"new configuration"を選択し、下記のように入力する。

RunConf.PNG

環境変数をEclipseにロードさせてビルド設定は終了。コマンドプロンプトで"PATH"をテキストに書き出し、その内容をEnviornmentに追加する。

   $path > %userprofile%\path.txt

RunConfPath.PNG

5-3. ビルドしてみる

これで作業完了。実際にビルドしてみる。

Run.PNG

Consoleでビルドができたことを確認。

BuildFinished.PNG

buildディレクトリ内のhtmlディレクトリ内に生成されたhtmlファイルが格納される。

htmlのソースが表示されてしまう場合は、html上で右クリックし、Open withでWeb Browserから開こう。

complete.PNG

6. おすすめの設定

6-1. blockdiag

シーケンス図やフローチャートがかけるようになる。

   $pip install sphinxcontrib.blockdiag blockdiag

以下のようにconf.pyを編集して拡張子の追加とフォントの指定を行う。

Blockdiag.PNG

6-2. sphinx_rtd_theme

お勧めのテーマが"sphinx_rtd_theme"。見やすいので使ってみる。

   $pip install sphinx_rtd_theme

以下のようにconf.pyを編集してテーマの変更を行う。

Theme.PNG

6-3. PC画面用に横幅をカスタマイズ

スマホ等でも見れるようにデフォルトでは横幅が固定されているが、PCでしか見ない資料ならば横幅固定を外したい場合はcss上書きする。
以下の内容のcssファイルをプロジェクトのディレクトリ内(\build\html_static\css\my_theme.css)に作成する。

   @import url("theme.css");

   .wy-nav-content {
       max-width: none;
   }

そして、以下のようにcond.pyを編集する。

Confpy.PNG

7. ドキュメントを書いてみる

まずは、Textファイルをsourceディレクトリ内に作成する。

NewFile.PNG

NewFile2.PNG

作成したら以下のようにindexのTreeにファイルを追加する。

Hello2.PNG

試しに以下のようなTextを書いてみる。

Hello1.PNG

Run(ビルド)してhtmlファイルを開くと・・・・。

Done.PNG

これで作業終了。あとは コード書く⇒ビルド⇒htmlの確認 を繰り返してドキュメントを書いていく。

htmlのソースが表示されてしまう場合は、html上で右クリックし、Open withでWeb Browserから開こう。

もしReSTエディターで一部文字化けが発生する場合、Window->Prederences->General->Apearance->Colors and FontsでFontを変更する。

MSGosic.PNG

8. GitHubで作成したドキュメントを公開

GitHubの使い方はまたいつか詳しく説明しようと思う。
とりあえず今回は公開の仕方のみ説明。

実際に私が公開しているGitHubのページを使って説明する。リンク(https://github.com/MarkInada/DocSphinxHowTo)

まずbuild/htmlディレクトリをコピーし、ディレクトリ名を"docs"にする。docs内に".nojekyll"という中身のないファイルを作る。

完了したらこのdocsディレクトリをリポジトリのプロジェクトルートにプッシュする。次にGitHubプロジェクトのSettingに行く。

GitHub1.PNG

Sourceで master branch /docs folder を選択し、Saveすると docs/index.html が公開される。

GitHub2.PNG

公開先のアドレスは、https://[ユーザー名].github.io/[リポジトリ名]/

README.md にURLを記載しておくと、以下のように表示され、便利である。

GitHub3.PNG

引用した資料たち

・Sphinxをはじめよう (http://sphinx-users.jp/gettingstarted/)

・Sphinx最初の一歩 (http://www.sphinx-doc.org/ja/1.7/tutorial.html#install-sphinx)

・reStructured Text in Eclipse (https://www.slideshare.net/tcalmant/rest-editor-eclipse-demo-camp-grenoble-2011)

・Sphinx再入門 (http://muraoka-edo.hatenablog.com/entry/2015/01/18/171522)

・sphinx_rtd_theme をカスタマイズする (http://kuttsun.blogspot.com/2016/11/sphinx-sphinxrtdtheme.html)

・blockdiag (http://blockdiag.com/ja/blockdiag/introduction.html)

・GitHub Pagesで自分の作ったサイトを公開する (https://qiita.com/nagisa88/items/91c4f57c784842f365d7)