Sphinx Advent Calendar 2012 (全部俺)

初心者がどのようにSphinxを使ってきたかという記録

第8日目 Sphinxドキュメントを編集する その5

昨日に引き続き リテラルブロック (コードブロック) 関連の説明です。

ソースコード等をファイルから読み込む

  • 別のファイルを読み込みリテラルブロックの表示をしたい時は literalinclude ディレクティブを使います。

    記述例:

    .. literalinclude:: ../../../files/yes_or_no.sh
       :language: bash
       :linenos:

    このように表示されます。

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    #!/bin/bash
    
    function yes_or_no_recursive(){
        echo
        echo "Type yes or no."
        read answer
        case $answer in
            yes)
                echo -e "tyeped yes.\n"
                return 0
                ;;
            no)
                echo -e "tyeped no.\n"
                return 1
                ;;
            *)
                echo -e "cannot understand $answer.\n"
                yes_or_no_recursive
                ;;
        esac
    }
    
    yes_or_no_recursive
    
  • language オプションを付ける事によりシンタックスハイライトが表示されます。

  • linenos オプションを付ける事により行番号が表示されます。

シンタックスハイライトで使える言語

  • Sphinxのシンタックスハイライトは pygments というライブラリを使っており、次のコマンドで対応一覧が出力できます。

    > pygmentize -L lexers

出力結果

  • * (アスタリスク) の行にある文字列が highlightcode-blockliteralincludelanguage オプションの引数として使えます。
Pygments version 1.5, (c) 2006-2011 by Georg Brandl.

Lexers:
~~~~~~~
* Cucumber, cucumber, Gherkin, gherkin:
    Gherkin (filenames *.feature)
* abap:
    ABAP (filenames *.abap)
* ada, ada95ada2005:
    Ada (filenames *.adb, *.ads, *.ada)
* ahk:
    autohotkey (filenames *.ahk, *.ahkl)
* antlr-as, antlr-actionscript:
    ANTLR With ActionScript Target (filenames *.G, *.g)
* antlr-cpp:
    ANTLR With CPP Target (filenames *.G, *.g)
* antlr-csharp, antlr-c#:
    ANTLR With C# Target (filenames *.G, *.g)
* antlr-java:
    ANTLR With Java Target (filenames *.G, *.g)
* antlr-objc:
    ANTLR With ObjectiveC Target (filenames *.G, *.g)
* antlr-perl:
    ANTLR With Perl Target (filenames *.G, *.g)
* antlr-python:
    ANTLR With Python Target (filenames *.G, *.g)
* antlr-ruby, antlr-rb:
    ANTLR With Ruby Target (filenames *.G, *.g)
* antlr:
    ANTLR 
* apacheconf, aconf, apache:
    ApacheConf (filenames .htaccess, apache.conf, apache2.conf)
* applescript:
    AppleScript (filenames *.applescript)
* as, actionscript:
    ActionScript (filenames *.as)
* as3, actionscript3:
    ActionScript 3 (filenames *.as)
* aspx-cs:
    aspx-cs (filenames *.aspx, *.asax, *.ascx, *.ashx, *.asmx, *.axd)
* aspx-vb:
    aspx-vb (filenames *.aspx, *.asax, *.ascx, *.ashx, *.asmx, *.axd)
* asy, asymptote:
    Asymptote (filenames *.asy)
* awk, gawk, mawk, nawk:
    Awk (filenames *.awk)
* basemake:
    Base Makefile 
* bash, sh, ksh:
    Bash (filenames *.sh, *.ksh, *.bash, *.ebuild, *.eclass, .bashrc, bashrc, .bash_*, bash_*)
* bat:
    Batchfile (filenames *.bat, *.cmd)
* bbcode:
    BBCode 
* befunge:
    Befunge (filenames *.befunge)
* blitzmax, bmax:
    BlitzMax (filenames *.bmx)
* boo:
    Boo (filenames *.boo)
* brainfuck, bf:
    Brainfuck (filenames *.bf, *.b)
* bro:
    Bro (filenames *.bro)
* c-objdump:
    c-objdump (filenames *.c-objdump)
* c:
    C (filenames *.c, *.h, *.idc)
* cfengine3, cf3:
    CFEngine3 (filenames *.cf)
* cfm:
    Coldfusion HTML (filenames *.cfm, *.cfml, *.cfc)
* cfs:
    cfstatement 
* cheetah, spitfire:
    Cheetah (filenames *.tmpl, *.spt)
* clojure, clj:
    Clojure (filenames *.clj)
* cmake:
    CMake (filenames *.cmake, CMakeLists.txt)
* coffee-script, coffeescript:
    CoffeeScript (filenames *.coffee)
* common-lisp, cl:
    Common Lisp (filenames *.cl, *.lisp, *.el)
* console:
    Bash Session (filenames *.sh-session)
* control:
    Debian Control file (filenames control)
* coq:
    Coq (filenames *.v)
* cpp, c++:
    C++ (filenames *.cpp, *.hpp, *.c++, *.h++, *.cc, *.hh, *.cxx, *.hxx)
* cpp-objdump, c++-objdumb, cxx-objdump:
    cpp-objdump (filenames *.cpp-objdump, *.c++-objdump, *.cxx-objdump)
* csharp, c#:
    C# (filenames *.cs)
* css+django, css+jinja:
    CSS+Django/Jinja 
* css+erb, css+ruby:
    CSS+Ruby 
* css+genshitext, css+genshi:
    CSS+Genshi Text 
* css+mako:
    CSS+Mako 
* css+myghty:
    CSS+Myghty 
* css+php:
    CSS+PHP 
* css+smarty:
    CSS+Smarty 
* css:
    CSS (filenames *.css)
* cython, pyx:
    Cython (filenames *.pyx, *.pxd, *.pxi)
* d-objdump:
    d-objdump (filenames *.d-objdump)
* d:
    D (filenames *.d, *.di)
* dart:
    Dart (filenames *.dart)
* delphi, pas, pascal, objectpascal:
    Delphi (filenames *.pas)
* diff, udiff:
    Diff (filenames *.diff, *.patch)
* django, jinja:
    Django/Jinja 
* dpatch:
    Darcs Patch (filenames *.dpatch, *.darcspatch)
* dtd:
    DTD (filenames *.dtd)
* duel, Duel Engine, Duel View, JBST, jbst, JsonML+BST:
    Duel (filenames *.duel, *.jbst)
* dylan:
    Dylan (filenames *.dylan, *.dyl)
* ec:
    eC (filenames *.ec, *.eh)
* ecl:
    ECL (filenames *.ecl)
* elixir, ex, exs:
    Elixir (filenames *.ex, *.exs)
* erb:
    ERB 
* erl:
    Erlang erl session (filenames *.erl-sh)
* erlang:
    Erlang (filenames *.erl, *.hrl, *.es, *.escript)
* evoque:
    Evoque (filenames *.evoque)
* factor:
    Factor (filenames *.factor)
* fan:
    Fantom (filenames *.fan)
* fancy, fy:
    Fancy (filenames *.fy, *.fancypack)
* felix, flx:
    Felix (filenames *.flx, *.flxh)
* fortran:
    Fortran (filenames *.f, *.f90, *.F, *.F90)
* fsharp:
    FSharp (filenames *.fs, *.fsi)
* gas:
    GAS (filenames *.s, *.S)
* genshi, kid, xml+genshi, xml+kid:
    Genshi (filenames *.kid)
* genshitext:
    Genshi Text 
* glsl:
    GLSL (filenames *.vert, *.frag, *.geo)
* gnuplot:
    Gnuplot (filenames *.plot, *.plt)
* go:
    Go (filenames *.go)
* gooddata-cl:
    GoodData-CL (filenames *.gdc)
* gosu:
    Gosu (filenames *.gs, *.gsx, *.gsp, *.vark)
* groff, nroff, man:
    Groff (filenames *.[1234567], *.man)
* groovy:
    Groovy (filenames *.groovy)
* gst:
    Gosu Template (filenames *.gst)
* haml, HAML:
    Haml (filenames *.haml)
* haskell, hs:
    Haskell (filenames *.hs)
* html+cheetah, html+spitfire:
    HTML+Cheetah 
* html+django, html+jinja:
    HTML+Django/Jinja 
* html+evoque:
    HTML+Evoque (filenames *.html)
* html+genshi, html+kid:
    HTML+Genshi 
* html+mako:
    HTML+Mako 
* html+myghty:
    HTML+Myghty 
* html+php:
    HTML+PHP (filenames *.phtml)
* html+smarty:
    HTML+Smarty 
* html+velocity:
    HTML+Velocity 
* html:
    HTML (filenames *.html, *.htm, *.xhtml, *.xslt)
* http:
    HTTP 
* hx, haXe:
    haXe (filenames *.hx)
* hybris, hy:
    Hybris (filenames *.hy, *.hyb)
* iex:
    Elixir iex session 
* ini, cfg:
    INI (filenames *.ini, *.cfg)
* io:
    Io (filenames *.io)
* ioke, ik:
    Ioke (filenames *.ik)
* irc:
    IRC logs (filenames *.weechatlog)
* jade, JADE:
    Jade (filenames *.jade)
* java:
    Java (filenames *.java)
* js+cheetah, javascript+cheetah, js+spitfire, javascript+spitfire:
    JavaScript+Cheetah 
* js+django, javascript+django, js+jinja, javascript+jinja:
    JavaScript+Django/Jinja 
* js+erb, javascript+erb, js+ruby, javascript+ruby:
    JavaScript+Ruby 
* js+genshitext, js+genshi, javascript+genshitext, javascript+genshi:
    JavaScript+Genshi Text 
* js+mako, javascript+mako:
    JavaScript+Mako 
* js+myghty, javascript+myghty:
    JavaScript+Myghty 
* js+php, javascript+php:
    JavaScript+PHP 
* js+smarty, javascript+smarty:
    JavaScript+Smarty 
* js, javascript:
    JavaScript (filenames *.js)
* json:
    JSON (filenames *.json)
* jsp:
    Java Server Page (filenames *.jsp)
* kotlin:
    Kotlin (filenames *.kt)
* lhs, literate-haskell:
    Literate Haskell (filenames *.lhs)
* lighty, lighttpd:
    Lighttpd configuration file 
* llvm:
    LLVM (filenames *.ll)
* logtalk:
    Logtalk (filenames *.lgt)
* lua:
    Lua (filenames *.lua, *.wlua)
* make, makefile, mf, bsdmake:
    Makefile (filenames *.mak, Makefile, makefile, Makefile.*, GNUmakefile)
* mako:
    Mako (filenames *.mao)
* maql:
    MAQL (filenames *.maql)
* mason:
    Mason (filenames *.m, *.mhtml, *.mc, *.mi, autohandler, dhandler)
* matlab:
    Matlab (filenames *.m)
* matlabsession:
    Matlab session 
* minid:
    MiniD (filenames *.md)
* modelica:
    Modelica (filenames *.mo)
* modula2, m2:
    Modula-2 (filenames *.def, *.mod)
* moocode:
    MOOCode (filenames *.moo)
* moon, moonscript:
    MoonScript (filenames *.moon)
* mupad:
    MuPAD (filenames *.mu)
* mxml:
    MXML (filenames *.mxml)
* myghty:
    Myghty (filenames *.myt, autodelegate)
* mysql:
    MySQL 
* nasm:
    NASM (filenames *.asm, *.ASM)
* nemerle:
    Nemerle (filenames *.n)
* newlisp:
    NewLisp (filenames *.lsp, *.nl)
* newspeak:
    Newspeak (filenames *.ns2)
* nginx:
    Nginx configuration file 
* nimrod, nim:
    Nimrod (filenames *.nim, *.nimrod)
* numpy:
    NumPy 
* objdump:
    objdump (filenames *.objdump)
* objective-c, objectivec, obj-c, objc:
    Objective-C (filenames *.m)
* objective-j, objectivej, obj-j, objj:
    Objective-J (filenames *.j)
* ocaml:
    OCaml (filenames *.ml, *.mli, *.mll, *.mly)
* octave:
    Octave (filenames *.m)
* ooc:
    Ooc (filenames *.ooc)
* opa:
    Opa (filenames *.opa)
* openedge, abl, progress:
    OpenEdge ABL (filenames *.p, *.cls)
* perl, pl:
    Perl (filenames *.pl, *.pm)
* php, php3, php4, php5:
    PHP (filenames *.php, *.php[345])
* plpgsql:
    PL/pgSQL 
* postgresql, postgres:
    PostgreSQL SQL dialect 
* postscript:
    PostScript (filenames *.ps, *.eps)
* pot, po:
    Gettext Catalog (filenames *.pot, *.po)
* pov:
    POVRay (filenames *.pov, *.inc)
* powershell, posh, ps1:
    PowerShell (filenames *.ps1)
* prolog:
    Prolog (filenames *.prolog, *.pro, *.pl)
* properties:
    Properties (filenames *.properties)
* protobuf:
    Protocol Buffer (filenames *.proto)
* psql, postgresql-console, postgres-console:
    PostgreSQL console (psql) 
* py3tb:
    Python 3.0 Traceback (filenames *.py3tb)
* pycon:
    Python console session 
* pypylog, pypy:
    PyPy Log (filenames *.pypylog)
* pytb:
    Python Traceback (filenames *.pytb)
* python, py:
    Python (filenames *.py, *.pyw, *.sc, SConstruct, SConscript, *.tac)
* python3, py3:
    Python 3 
* ragel-c:
    Ragel in C Host (filenames *.rl)
* ragel-cpp:
    Ragel in CPP Host (filenames *.rl)
* ragel-d:
    Ragel in D Host (filenames *.rl)
* ragel-em:
    Embedded Ragel (filenames *.rl)
* ragel-java:
    Ragel in Java Host (filenames *.rl)
* ragel-objc:
    Ragel in Objective C Host (filenames *.rl)
* ragel-ruby, ragel-rb:
    Ragel in Ruby Host (filenames *.rl)
* ragel:
    Ragel 
* raw:
    Raw token data 
* rb, ruby, duby:
    Ruby (filenames *.rb, *.rbw, Rakefile, *.rake, *.gemspec, *.rbx, *.duby)
* rbcon, irb:
    Ruby irb session 
* rconsole, rout:
    RConsole (filenames *.Rout)
* rebol:
    REBOL (filenames *.r, *.r3)
* redcode:
    Redcode (filenames *.cw)
* rhtml, html+erb, html+ruby:
    RHTML (filenames *.rhtml)
* rst, rest, restructuredtext:
    reStructuredText (filenames *.rst, *.rest)
* sass, SASS:
    Sass (filenames *.sass)
* scala:
    Scala (filenames *.scala)
* scaml, SCAML:
    Scaml (filenames *.scaml)
* scheme, scm:
    Scheme (filenames *.scm, *.ss, *.rkt)
* scilab:
    Scilab (filenames *.sci, *.sce, *.tst)
* scss:
    SCSS (filenames *.scss)
* smalltalk, squeak:
    Smalltalk (filenames *.st)
* smarty:
    Smarty (filenames *.tpl)
* sml:
    Standard ML (filenames *.sml, *.sig, *.fun)
* snobol:
    Snobol (filenames *.snobol)
* sourceslist, sources.list:
    Debian Sourcelist (filenames sources.list)
* splus, s, r:
    S (filenames *.S, *.R)
* sql:
    SQL (filenames *.sql)
* sqlite3:
    sqlite3con (filenames *.sqlite3-console)
* squidconf, squid.conf, squid:
    SquidConf (filenames squid.conf)
* ssp:
    Scalate Server Page (filenames *.ssp)
* sv:
    systemverilog (filenames *.sv, *.svh)
* tcl:
    Tcl (filenames *.tcl)
* tcsh, csh:
    Tcsh (filenames *.tcsh, *.csh)
* tea:
    Tea (filenames *.tea)
* tex, latex:
    TeX (filenames *.tex, *.aux, *.toc)
* text:
    Text only (filenames *.txt)
* trac-wiki, moin:
    MoinMoin/Trac Wiki markup 
* urbiscript:
    UrbiScript (filenames *.u)
* v:
    verilog (filenames *.v)
* vala, vapi:
    Vala (filenames *.vala, *.vapi)
* vb.net, vbnet:
    VB.net (filenames *.vb, *.bas)
* velocity:
    Velocity (filenames *.vm, *.fhtml)
* vhdl:
    vhdl (filenames *.vhdl, *.vhd)
* vim:
    VimL (filenames *.vim, .vimrc, .exrc, .gvimrc, _vimrc, _exrc, _gvimrc, vimrc, gvimrc)
* xml+cheetah, xml+spitfire:
    XML+Cheetah 
* xml+django, xml+jinja:
    XML+Django/Jinja 
* xml+erb, xml+ruby:
    XML+Ruby 
* xml+evoque:
    XML+Evoque (filenames *.xml)
* xml+mako:
    XML+Mako 
* xml+myghty:
    XML+Myghty 
* xml+php:
    XML+PHP 
* xml+smarty:
    XML+Smarty 
* xml+velocity:
    XML+Velocity 
* xml:
    XML (filenames *.xml, *.xsl, *.rss, *.xslt, *.xsd, *.wsdl)
* xquery, xqy:
    XQuery (filenames *.xqy, *.xquery)
* xslt:
    XSLT (filenames *.xsl, *.xslt)
* yaml:
    YAML (filenames *.yaml, *.yml)

明日はSphinxドキュメントを構造化する重要な toctree ディレクティブについて説明します。

※ このアドベントカレンダーについては このアドベントカレンダーについて を参照して下さい。

第7日目 Sphinxドキュメントを編集する その4

今日ご紹介するのは リテラルブロック (コードブロック) の書き方です。

Sphinxで リテラルブロック とはプログラムのソースコードやコマンドライン、他にエスケープ文字やSphinxで解釈されてしまうreST表記やディレクティブ等をそのまま表示させたい時に使う方法です。

リテラルブロック

  • :: (コロン×2) の次に空行を空けてインデントをして記述します。

    記述例:

    ::
    
     def fizzbuzz(a):
         if not(a%15):
             print "fizzbuzz"
         elif not(a%5):
             print "buzz"
         elif not(a%3):
             print "fizz"
         else:
             print a
    
     map(fizzbuzz,range(1,100))
    

    このように表示されます。:

    def fizzbuzz(a):
        if not(a%15):
            print "fizzbuzz"
        elif not(a%5):
            print "buzz"
        elif not(a%3):
            print "fizz"
        else:
            print a
    
    map(fizzbuzz,range(1,100))
    
  • :: (コロン×2) の前に文字列を入れた場合は、文字列の後に : (コロン) が1つ表示されます。上記の例で使用している 記述例:: を見て下さい。

シンタックスハイライト

  • :: (コロン×2) より前に highlight ディレクティブを入れる事によりシンタックスハイライトする事ができます。

    記述例:

    .. highlight:: python
       :linenothreshold: 5
    
    記述例::
    
      def fizzbuzz(a):
        if not(a%15):
          print "fizzbuzz"
        elif not(a%5):
          print "buzz"
        elif not(a%3):
          print "fizz"
        else:
          print a
    
      map(fizzbuzz,range(1,100))
    

    このように表示されます。

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    import os
    def fizzbuzz(a):
        not(a%15):
            print "fizzbuzz"
        elif not(a%5):
            print "buzz"
        elif not(a%3):
            print "fizz"
        else:
            print a
    
    map(fizzbuzz,range(1,100))
    
  • 1つのreSTファイルの頭に .. highlight:: python を入れておくと以降のリテラルブロックはPythonのシンタックスハイライトが適用されます。

  • linenothreshold というオプションを付けると行番号が表示されます。 :linenothreshold: 5 の場合は5行以上ある場合に行番号が表示されます。

  • highlightcode-block で使える言語の引数は こちら

code-blockディレクティブ

  • :: (コロン×2)highlight ディレクティブの組み合わせで、リテラルブロック+シンタックスハイライトを表示させてきましたが code-block ディレクティブのみで表示させる事も可能です。1つのreSTファイルの中に異なるシンタックスハイライトで表示させたい場合に使います。

    記述例:

    .. code-block:: awk
       :linenos:
    
       #!/usr/bin/gawk
       BEGIN{i=0
           while (i<100) {
                          i++
                          fizzbuzz(i)
                          }
       }
       function fizzbuzz(a){
           if (!index(a / 15,".")) print "FizzBuzz"
               else
                   if (!index(a / 3,".")) print "Fizz"
                       else
                           if (!index(a / 5,".")) print "Buzz"
                               else
                                   print a
       }
    

    このように表示されます。

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    #!/usr/bin/gawk
    BEGIN{i=0
        while (i<100) {
                       i++
                       fizzbuzz(i)
                       }
    }
    function fizzbuzz(a){
        if (!index(a / 15,".")) print "FizzBuzz"
            else
                if (!index(a / 3,".")) print "Fizz"
                    else
                        if (!index(a / 5,".")) print "Buzz"
                            else
                                print a
    }
    

明日は引き続き リテラルブロック 関連について説明します。

※ このアドベントカレンダーについては このアドベントカレンダーについて を参照して下さい。