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

• 別のファイルを読み込みリテラルブロックの表示をしたい時は 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 ディレクティブについて説明します。

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