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

• 別のファイルを読み込みリテラルブロックの表示をしたい時は 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

出力結果

• * (アスタリスク) の行にある文字列が highlight や code-block 、 literalinclude の language オプションの引数として使えます。

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 ディレクティブについて説明します。

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

リテラルブロック

• :: (コロン×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つ表示されます。上記の例で使用している 記述例:: を見て下さい。

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 }

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

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