yuuho.wiki

カオスの欠片を集めて知恵の泉を作る

ユーザ用ツール

サイト用ツール

現在位置: start » tips » sphinx
トレース: • study
tips:sphinx:start

差分

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

この比較画面へのリンク

両方とも前のリビジョン前のリビジョン
次のリビジョン		前のリビジョン
tips:sphinx:start [2022/03/16 06:19] – [始め方] yuuhotips:sphinx:start [2022/03/16 08:06] (現在) – [設定の変更など] yuuho
行 8: 行 8:
  
 ===== 始め方 ===== ===== 始め方 =====
 +==== 環境構築 ====
 +
 +色々なやり方がありそう。 ''conda'' で環境に入れてしまうのが良さげ。
 +
 +<code bash>sudo apt install python3-sphinx</code>
 +
 +<code bash>conda install sphinx</code>
 +
 +<code bash>pip install -U sphinx</code>
 +
 +==== sphinx ファイル作成 ====
 +
 リポジトリにドキュメントを追加するときに何から始めるか。 リポジトリにドキュメントを追加するときに何から始めるか。
  
行 71: 行 83:
     - ./build/     - ./build/
     - ./source/     - ./source/
 +      - ./source/_static/
 +      - ./source/_templates/
 +      - ./source/conf.py
 +      - ./source/index.rst
     - ./make.bat     - ./make.bat
     - ./Makefile     - ./Makefile
行 76: 行 92:
 となった。 となった。
  
-=== ページの生成 ===+==== ページの生成 (make html) で生成されるファイル ====
  
 +=== 生成 ===
 ''.'' で <code bash>make html</code> すればよい。 ''.'' で <code bash>make html</code> すればよい。
  
 +=== 結果 ===
 実行したディレクトリを ''.'' とすると 実行したディレクトリを ''.'' とすると
 <code> <code>
行 87: 行 105:
       - ./build/html      : gh-pages として公開すれば良いディレクトリ       - ./build/html      : gh-pages として公開すれば良いディレクトリ
     - ./source/     - ./source/
 +      - ./source/_static/
 +      - ./source/_templates/
 +      - ./source/conf.py
 +      - ./source/index.rst
     - ./make.bat     - ./make.bat
     - ./Makefile     - ./Makefile
 </code> </code>
 となった。 となった。
 +
 +===== 開発 =====
 +
 +''build/html/'' の中で ''python -m http.server'' すれば良い。\\
 +なので、 ''build/html/'' さえ gh-pages で公開すれば良さそう。\\
 +-> github pages は jekyll というソフトで実装されているため相対リンクなどを有効にするために特殊な設定が必要。\\
 +-> 拡張機能を入れるべし。
 +
 +
 +===== 設定の変更など =====
  
 === メモ === === メモ ===
  
 +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>
tips/sphinx/start.1647411560.txt.gz · 最終更新: 2022/03/16 06:19 by yuuho