tk0miya

preface and appendix for Sphinx

tk0miya

"""
autodoc: show default value of arguments as is
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:license: Same as Sphinx
"""

import ast
import inspect
from typing import Any, Dict

tk0miya

`````
CommonMark では fenced code block の終了は、開始マーカーと同じかそれ以上の backtick を必要とします。
```
ですので、まだここはコードブロックの中です。
``````````
そして、ここはコードブロックの外です。

また、fenced code block は backtick か tilde をマーカーに利用できると定義されているので
~~~
ここはコードブロックですし

tk0miya

# extension testbed
# autodoc_typehints_docinfo -- typehint をいい感じに表示する拡張
#
# * 型情報は typehint を書いておいてね
# * conf.py で autodoc_typehints = 'docinfo' と設定する

from docutils import nodes
from sphinx import addnodes
from sphinx.util.docfields import DocFieldTransformer
from sphinx.util.inspect import Signature

tk0miya

# extension testbed
# Description: ``:index:`` ロールのタイトルを強調表示する
from docutils import nodes

from sphinx import addnodes
from sphinx.transforms import SphinxTransform


class IndexStyleTransform(SphinxTransform):
    default_priority = 200

tk0miya

Sphinx でも絵文字を使ってみたい

github っぽく emoji を使ってみたいので、 GitHub の emoji ライブラリ gemoji から絵文字の定義リストを拝借して Sphinx に突っ込んで見るテスト。substitution 文法を拝借したので |+1| とすると絵文字が出ます。

Unicode の文字をそのまま埋め込んでいるので、PDF 出力する場合は Unicode 対応の LaTeX エンジンといい感じのフォントを使ってください。 つまり、デフォルトでは動作しません。

使い方

tk0miya

image: tk0miya/sphinx-pdf
pages:
  script:
  - kanji-config-updmap-sys ipaex
  - make epub html latexpdf
  - mkdir build/html/files
  - mv build/latex/docutils.pdf build/html/files/mastering_docutils-v1.0.pdf
  - mv build/epub/docutils.epub build/html/files/mastering_docutils-v1.0.epub
  - mv build/html/ docutils
  - zip -r docutils.zip docutils/

tk0miya

# extension testbed

"""
autodoc でサブクラスを表示してみる。
"""


from docutils import nodes
from sphinx import addnodes
from sphinx.transforms import SphinxTransform

tk0miya

まだお酒が残っているので gist に下書き。そのうち昇華してブログにでもするのではないだろうか。

技術書典7 で『Inside Sphinx』を頒布しているとき、お客さんから質問をひとつもらった。
質問の内容は極めてシンプルで、「本文中のある要素をクリックするごとに表示/非表示を切り替えるにはどうするとよいか」というものであった。
その場ではいいアイディアが出てこなかったため、CSS + JS で解決するとよいのではと答えたのだけど、
よくよく考えてみるとこれは HTML5 で導入された `<details>` タグの挙動そのものなのであった。

さて、期待されるアウトプットが整理できたところで、この課題を解決するにはどういうアプローチがよいだろうか。
ぱっと思い浮かぶ選択肢はいくつかある。どういうものが思いつくだろうか。そして、どれを選ぶべきだろう。

tk0miya

# extension testbed


from docutils import nodes
from docutils.parsers.rst import Directive
from sphinx.transforms.post_transforms import SphinxPostTransform
from sphinx.util.nodes import NodeMatcher


class details(nodes.Element, nodes.General):