差分

このページの2つのバージョン間の差分を表示します。

--- tips:sphinx:start [2022/03/16 05:53] – yuuho
+++ tips:sphinx:start [2022/03/16 08:06] (現在) – [設定の変更など] yuuho
@@ 行 7: / 行 7: @@
     * デバッグなどの様子を見せるのに使う
-=== get started ===
+===== 始め方 =====
+==== 環境構築 ====
+色々なやり方がありそう。 ''conda'' で環境に入れてしまうのが良さげ。
+<code bash>sudo apt install python3-sphinx</code>
+<code bash>conda install sphinx</code>
+<code bash>pip install -U sphinx</code>
+==== sphinx ファイル作成 ====
 リポジトリにドキュメントを追加するときに何から始めるか。
 以下のコマンドで対話が始まって自動で作成される。とりあえず build のディレクトリは分ける設定で良さそう？
 <code bash>sphinx-quickstart</code>
+  * 対話の詳細 ↓ (クリックで展開可能) <html><details><summary>対話内容</summary><pre>
+Sphinx 2.1.2 クイックスタートユーティリティへようこそ。
+以下の設定値を入力してください（Enter キーのみ押した場合、
+かっこで囲まれた値をデフォルト値として受け入れます）。
+選択されたルートパス: .
+Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
+ルートパス内にある "_build" ディレクトリを使うか、
+ルートパス内に "source" と "build" ディレクトリを分ける方法です。
+> ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: y
+以下の設定値を入力してください（Enter キーのみ押した場合、
+かっこで囲まれた値をデフォルト値として受け入れます）。
+選択されたルートパス: .
+Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
+ルートパス内にある "_build" ディレクトリを使うか、
+ルートパス内に "source" と "build" ディレクトリを分ける方法です。
+> ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: y
+プロジェクト名は、ビルドされたドキュメントのいくつかの場所にあります。
+> プロジェクト名: hogehoge
+> 著者名（複数可）: fugafuga
+> プロジェクトのリリース []: piyopiyo
+If the documents are to be written in a language other than English,
+you can select a language here by its language code. Sphinx will then
+translate text that it generates into that language.
+For a list of supported codes, see
+https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
+> プロジェクトの言語 [en]: en
+ファイル ./source/conf.py を作成しています。
+ファイル ./source/index.rst を作成しています。
+ファイル ./Makefile を作成しています。
+ファイル ./make.bat を作成しています。
+終了：初期ディレクトリ構造が作成されました。
+マスターファイル ./source/index.rst を作成して
+他のドキュメントソースファイルを作成します。次のように Makefile を使ってドキュメントを作成します。
+ make builder
+"builder" はサポートされているビルダーの 1 つです。 例: html, latex, または linkcheck。
+</pre></details></html>
+===== ディレクトリ構成など =====
+==== sphinx-quickstart で生成されるファイル ====
+実行したディレクトリを ''.'' とすると
+<code>
+- ./
+    - ./build/
+    - ./source/
+      - ./source/_static/
+      - ./source/_templates/
+      - ./source/conf.py
+      - ./source/index.rst
+    - ./make.bat
+    - ./Makefile
+</code>
+となった。
+==== ページの生成 (make html) で生成されるファイル ====
+=== 生成 ===
+''.'' で <code bash>make html</code> すればよい。
+=== 結果 ===
 実行したディレクトリを ''.'' とすると
 <code>
@@ 行 20: / 行 105: @@
       - ./build/html      : gh-pages として公開すれば良いディレクトリ
     - ./source/
+      - ./source/_static/
+      - ./source/_templates/
+      - ./source/conf.py
+      - ./source/index.rst
     - ./make.bat
     - ./Makefile
 </code>
 となった。
+===== 開発 =====
+''build/html/'' の中で ''python -m http.server'' すれば良い。\\
+なので、 ''build/html/'' さえ gh-pages で公開すれば良さそう。\\
+-> github pages は jekyll というソフトで実装されているため相対リンクなどを有効にするために特殊な設定が必要。\\
+-> 拡張機能を入れるべし。
+===== 設定の変更など =====
 === メモ ===
-''make html'' すればよい。
+github-pages で公開する場合はすべてのファイルを相対リンク？するように拡張機能を入れるのが良さそう。
+[[https://kuma8.hatenablog.jp/entry/20110925/1316937363]]
-何を git 管理するべき？
+  * 拡張機能
+    * ''./source/conf.py'' の ''extensions'' という listオブジェクトの中に以下の文字列を追加。\\ 特にインストール操作など必要ない。書き込むだけ。
+      * ''"sphinx.ext.githubpages"''
-''build/html/'' の中で ''python -m http.server'' すれば良い。\\
+=== メモ2 ===
-なので、 ''build/html/'' さえ gh-pages で公開すれば良さそう。
+<code>
+.. hoge::
+</code>
+みたいな感じで hoge 機能を使える。
+使える機能としては ''toctree'' や ''index'' ''note'' ''warning'' などある。
+<code>
+.. fuga fuga piyo piyo
+</code>
+で単純にコメントを書く。
+=== メモ3 ===
+よく使われているテーマ。
+[[https://qiita.com/ganyariya/items/543e5bc55ef0777cbd0c]]
+<code bash>pip install sphinx-rtd-theme</code>
+<code python conf.py>
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.todo',
+    'sphinx.ext.napoleon',
+    'sphinx_rtd_theme'
+]
+html_theme = 'sphinx_rtd_theme'
+</code>