sphinx
==========================

__init__.py
-------------------------

addnodes.py
-------------------------

docutilsのnodesにノードを追加する

.. code-block:: python

   nodes._add_node_class_names("""index desc desc_content desc_signature
      desc_type desc_returns desc_addname desc_name desc_parameterlist
      desc_parameter desc_optional download_reference hlist hlistcol
      centered versionmodified seealso productionlist production toctree
      pending_xref compact_paragraph highlightlang literal_emphasis
      abbreviation glossary acks module start_of_file tabular_col_spec
      meta""".split())

application.py
-------------------------

cmdline.py
-------------------------

sphinx-buildで呼ばれる。

.. code-block:: python

   app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername,
         confoverrides, status, warning, freshenv,
         warningiserror, tags)
   app.build(force_all, filenames)
   return app.statuscode

Sphinxはsphinx.applicationで定義されている

.. code-block:: python

   from sphinx.application import Sphinx


config.py
-------------------------

execfileの第二引数って何かな？と思ったので調べた

.. code-block:: python

   config = {}
   execfile(config['__file__'], config)

.. code-block:: sh

   execfile(...)
       execfile(filename[, globals[, locals]])
       
       Read and execute a Python script from a file.
       The globals and locals are dictionaries, defaulting to the current
       globals and locals.  If only globals is given, locals defaults to it.

environment.py
-------------------------

errors.py
-------------------------

sphinxのエラークラスが記述されてる

highlighting.py
-------------------------

pygmentsによるコードハイライト

try/except/elseはあとで調べる

jinja2glue.py
-------------------------

glueらしいがよくわからん

.. code-block:: sh

   builders/__init__.py
   72:            from sphinx.jinja2glue import BuiltinTemplateLoader
   
   ext/autosummary/generate.py
   30:from sphinx.jinja2glue import BuiltinTemplateLoader
   
   jinja2glue.py
   3:    sphinx.jinja2glue

quickstart.py
-------------------------

sphinx-quickstartコマンドの中身。Makefile等をここで作成している。

raw_inputで入力したデータをdecodeする流れは参考になる。

.. code-block:: python

   def do_prompt(d, key, text, default=None, validator=nonempty):
       while True:
           if default:
               prompt = purple(PROMPT_PREFIX + '%s [%s]: ' % (text, default))
           else:
               prompt = purple(PROMPT_PREFIX + text + ': ')
           x = raw_input(prompt)
           if default and not x:
               x = default
           if x.decode('ascii', 'replace').encode('ascii', 'replace') != x:
               if TERM_ENCODING:
                   x = x.decode(TERM_ENCODING)
               else:
                   print turquoise('* Note: non-ASCII characters entered '
                                   'and terminal encoding unknown -- assuming '
                                   'UTF-8 or Latin-1.')
                   try:
                       x = x.decode('utf-8')
                   except UnicodeDecodeError:
                       x = x.decode('latin1')
           try:
               x = validator(x)
           except ValidationError, err:
               print red('* ' + str(err))
               continue
           break
       d[key] = x

roles.py
-------------------------

Handlers for additional ReST roles.

docutils理解しないとわかんないな

search.py
-------------------------

オフラインサーチ用

sphinxではリストを作るのに文字列をsplitするやり方を見ることが多い。
辞書順に並べておくと保守がやりやすいのかな？

.. code-block:: python

   stopwords = set("""
   a  and  are  as  at
   be  but  by
   for
   if  in  into  is  it
   near  no  not
   of  on  or
   such
   that  the  their  then  there  these  they  this  to
   was  will  with
   """.split())

setup_command.py
-------------------------

Setuptools/distutils用のセットアップスクリプト
cmdline.pyのsetuptool版

theming.py
-------------------------

テーマの設定とか

reverse

.. code-block:: python

   cls.themepath[::-1]

writers/
-------------------------