差分

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

--- tips:sphinx:start [2022/03/16 06:09] – 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 ファイル作成 ====
 リポジトリにドキュメントを追加するときに何から始めるか。
@@ 行 13: / 行 25: @@
 <code bash>sphinx-quickstart</code>
-  * 対話の詳細 ↓
+  * 対話の詳細 ↓ (クリックで展開可能) <html><details><summary>対話内容</summary><pre>
-<html><details><pre>
 Sphinx 2.1.2 クイックスタートユーティリティへようこそ。
@@ 行 63: / 行 74: @@
 </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>
@@ 行 72: / 行 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>