Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
16
Help us understand the problem. What is going on with this article?
@tcsh

[Sphinx] #1 Sphinx Quick Start

More than 3 years have passed since last update.

前提条件

1. プロジェクトの作成

1.1. プロジェクトディレクトリの作成

変数の設定
DIR_HANDSON="${HOME}/$( date +%Y%m%d )-handson" \
     && echo ${DIR_HANDSON}
コマンド
mkdir -p ${DIR_HANDSON}/main \
     && cd ${DIR_HANDSON}/main

(任意) バージョン管理の開始

Marcurialの場合
hg init
コマンド
cat << EOF >> .hgignore
^_build
^_warn.log
\.sw.$
\.DS_Store$
EOF

hg add .hgignore
hg add *

1.2. Sphinxプロジェクト名の決定

変数の設定
SP_PROJECT="Sphinx Handson ($( date +%Y%m%d) )" \
     && echo "${SP_PROJECT}"

1.3. 著者名の決定

変数の設定
SP_AUTHOR='<著者名>'

1.4. プロジェクトのバージョン決定

変数の設定
SP_VERSION='1.0'

1.5. 言語の決定

変数の設定
SP_LANG='ja'

1.6. Sphinxのプロジェクト作成

変数の確認
cat << ETX

     SP_PROJECT: ${SP_PROJECT}
     SP_AUTHOR:  ${SP_AUTHOR}
     SP_VERSION: ${SP_VERSION}
     SP_LANG:    ${SP_LANG}

ETX
コマンド
sphinx-quickstart \
  -q \
  -p "${SP_PROJECT}" \
  -a "${SP_AUTHOR}" \
  -v "${SP_VERSION}" \
  -l ${SP_LANG}
結果(例)
   Finished: An initial directory structure has been created.

   You should now populate your master file ./index.rst and create other documentation
   source files. Use the Makefile to build the docs, like so:
      make builder
   where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

注釈: Windows用のmake.batが不要な場合、--no-batchfileを付ける。

コマンド
ls -1F
結果(例)
   Makefile
   _build/
   _static/
   _templates/
   conf.py
   index.rst
   make.bat

生成されたファイル

index.rst
ドキュメントの本体となるファイルです。このファイルにドキュメントを記述します。

conf.py
Sphinxの設定ファイルです。Pythonの言語仕様に従って記述します。

Makefile
UNIX系OS用のドキュメントビルドツールです。

make.bat
Windows OS用のドキュメントビルドツールです。

生成されたディレクトリ

_build
ビルドされたドキュメントが格納されます。

_static
静的なファイルを格納します。

_templates
個人的には使ったことないです。

2. ドキュメントの生成

コマンド
make html
結果(例)
   sphinx-build -b html -d _build/doctrees   . _build/html
   Running Sphinx v1.3.1
   making output directory...
   loading translations [ja]... done
   loading pickled environment... not yet created
   building [mo]: targets for 0 po files that are out of date
   building [html]: targets for 1 source files that are out of date
   updating environment: 1 added, 0 changed, 0 removed
   reading sources... [100%] index

   looking for now-outdated files... none found
   pickling environment... done
   checking consistency... done
   preparing documents... done
   writing output... [100%] index

   generating indices... genindex
   writing additional pages... search
   copying static files... done
   copying extra files... done
   dumping search index in Japanese (code: ja) ... done
   dumping object inventory... done
   build succeeded.

   Build finished. The HTML pages are in _build/html.
コマンド(全て作り直す場合)
make clean && make html
結果(例)
   rm -rf _build/*
   sphinx-build -b html -d _build/doctrees   . _build/html
   (略)
   build succeeded.

   Build finished. The HTML pages are in _build/html.

生成されたドキュメントは、_build/[形式]の下に置かれます。

コマンド
ls -1F _build/html/
結果(例)
   _sources/
   _static/
   genindex.html
   index.html
   objects.inv
   search.html
   searchindex.js
コマンド
cat _build/html/index.html
結果(例)
   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


   <html xmlns="http://www.w3.org/1999/xhtml">
     <head>
       <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

       <title>Welcome to Sphinx Handson (20150720)’s documentation! &mdash; Sphinx Handson (20150720) 1.0 ドキュメント</title>

       <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />

       <script type="text/javascript">
         var DOCUMENTATION_OPTIONS = {
           URL_ROOT:    './',
           VERSION:     '1.0',
           COLLAPSE_INDEX: false,
           FILE_SUFFIX: '.html',
           HAS_SOURCE:  true
         };
       </script>
       <script type="text/javascript" src="_static/jquery.js"></script>
       <script type="text/javascript" src="_static/underscore.js"></script>
       <script type="text/javascript" src="_static/doctools.js"></script>
       <script type="text/javascript" src="_static/translations.js"></script>
       <link rel="top" title="Sphinx Handson (20150720) 1.0 ドキュメント" href="#" />


     <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">

     </head>
     <body role="document">
       <div class="related" role="navigation" aria-label="related navigation">
         <h3>ナビゲーション</h3>
         <ul>
           <li class="right" style="margin-right: 10px">
             <a href="genindex.html" title="総合索引"
                accesskey="I">索引</a></li>
           <li class="nav-item nav-item-0"><a href="#">Sphinx Handson (20150720) 1.0 ドキュメント</a> &raquo;</li> 
         </ul>
       </div>  

       <div class="document">
         <div class="documentwrapper">
           <div class="bodywrapper">
             <div class="body" role="main">

     <div class="section" id="welcome-to-sphinx-handson-20150720-s-documentation">
   <h1>Welcome to Sphinx Handson (20150720)&#8217;s documentation!<a class="headerlink" href="#welcome-to-sphinx-handson-20150720-s-documentation" title="このヘッドラインへのパーマリンク"></a></h1>
   <p>Contents:</p>
   <div class="toctree-wrapper compound">
   <ul class="simple">
   </ul>
   </div>
   </div>
   <div class="section" id="indices-and-tables">
   <h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="このヘッドラインへのパーマリンク"></a></h1>
   <ul class="simple">
   <li><a class="reference internal" href="genindex.html"><span>索引</span></a></li>
   <li><a class="reference internal" href="py-modindex.html"><span>モジュール索引</span></a></li>
   <li><a class="reference internal" href="search.html"><span>検索ページ</span></a></li>
   </ul>
   </div>


             </div>
           </div>
         </div>
         <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
           <div class="sphinxsidebarwrapper">
     <h3><a href="#">目次</a></h3>
     <ul>
   <li><a class="reference internal" href="#">Welcome to Sphinx Handson (20150720)&#8217;s documentation!</a></li>
   <li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
   </ul>

     <div role="note" aria-label="source link">
       <h3>このページ</h3>
       <ul class="this-page-menu">
         <li><a href="_sources/index.txt"
               rel="nofollow">ソースコードを表示</a></li>
       </ul>
      </div>
   <div id="searchbox" style="display: none" role="search">
     <h3>クイック検索</h3>
       <form class="search" action="search.html" method="get">
         <input type="text" name="q" />
         <input type="submit" value="検索" />
         <input type="hidden" name="check_keywords" value="yes" />
         <input type="hidden" name="area" value="default" />
       </form>
       <p class="searchtip" style="font-size: 90%">
       モジュール、クラス、または関数名を入力してください
       </p>
   </div>
   <script type="text/javascript">$('#searchbox').show(0);</script>
           </div>
         </div>
         <div class="clearer"></div>
       </div>
       <div class="footer">
         &copy;2015, Hirokazu HATANO.

         |
         Powered by <a href="http://sphinx-doc.org/">Sphinx 1.3.1</a>
         &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.2</a>

         |
         <a href="_sources/index.txt"
             rel="nofollow">Page source</a></li>
       </div>




     </body>
   </html>

3. Sphinxのカスタマイズ

3.1. Makefileのカスタマイズ

make実行時のエラーログを保存する設定をしておきます。

コマンド
mv Makefile Makefile.org \
   && cat Makefile.org | sed 's/SPHINXOPTS    =$/SPHINXOPTS    = -w _warn.log/' > Makefile \
   && diff Makefile.org Makefile
結果(例)
   5c5
   < SPHINXOPTS    =
   ---
   > SPHINXOPTS    = -w _warn.log

3.2. conf.pyのカスタマイズ

Sphinxの各種設定は conf.py で行います。

  • extensions: 拡張の組み込み
  • html_theme: テーマ名
  • など
設定の追加(サンプル)
cat << EOF >> conf.py

# for HTML
html_theme = 'bizstyle'
html_title = project

# for PDF
language = 'ja'
latex_docclass = {'manual': 'jsbook'}

# define for replace
today_fmt = '%Y-%m-%d'
EOF

cat conf.py

3.3. index.rstのリネーム

このハンズオンではオリジナルのindex.rstは使用しないので、リネームしておきます。

コマンド
mv index.rst origin-index.txt

注釈: Sphinxでは拡張子rstのファイルに対して自動リンクするので、拡張子をtxt に変えておきます。

完了

16
Help us understand the problem. What is going on with this article?
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away

Comments

No comments
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account Login
16
Help us understand the problem. What is going on with this article?