Sphinx customization for OGP support at SphinxCon JP 2018

Takayuki Shimizukawa
Takayuki ShimizukawaWeb Developer at BePROUD Inc.
1
おまえ誰よ
清水川 貴之 @shimizukawa
BeProud, Inc.
- connpass, PyQ
一般社団法人PyCon JP
- 理事, PyCamp講師
Sphinx - co-maintainer
- Sphinx-users.jp
2
で書いた書籍(ここ 年)
3
2017/10/20
Sphinxをはじめよ
う 第2版
2018/2/23
独学プログラマー
2018/6/12
Python プロフェッ
ショナルプログラミン
グ第3版
2018/2/26
エキスパート
Pythonプログラミ
ング改訂2版
で書いたよ
今日の シャツ
4
5
翻訳
● 月1回、週末にSphinxのユーザーと、翻訳する人が集まっ
て、各自好きなことをやるイベントです。
● 参加者はだいたい 4~8人
● sphinx
● documentation
● translation
● 場所:
● 東京の曙橋・市ヶ谷
6
sphinxjp.connpass.com hack-a-thon
● 2018/12/04(火) 19:30 〜 21:30
● 場所: 市ヶ谷 アルファーロ(イタリアン)
● SphinxのSlackかGoogle Group (ML)に入ってれば参加
OK
総会 忘年会
7
sphinxjp.connpass.com 総会 / 忘年会
● 2019/1月?2月?
● 場所: 国立女性教育会館 (埼玉県 嵐山)
● もくもく
開発合宿
8
sphinxjp.connpass.com 合宿
9
What is Sphinx?
Sphinx はドキュメンテーションジェネレーター
Sphinxは1つのreSTマークアップのソースから、
複数のファイル形式に出力できます
10
Sphinx
reSTreSTreStructuredText
(reST) reST Parser
HTML Builder
ePub Builder
LaTeX Builder texlive
HTML
theme
Favorite Editor
多くのドキュメントがSphinx製
For examples
● Python libraries/tools:
Python, Sphinx, Zope, Plone, Pyramid, Django,
Flask, SQLAlchemy, Numpy, SciPy,
scikit-learn, pandas, fabric, ansible, awscli, …
● Non python libraries/tools:
Chef, CakePHP(2.x), MathJax, Selenium,
Varnish
11
SPHINX
docutils
HTML Builder HTML theme
(Jinja2)
拡張のメカニズム
12
reST Parser
(directive / role)
doctree
(Intermediate)
reSTreST
reStructuredText
(reST)
Sphinx拡張
カスタム記法を追
加
(ディレクティブと
ロール)
Sphinxのビル
ドステージに割
込み
And more...
出力形式
の追加
拡張ができることは
13
● OGP = Open Graph Protocol.
● OGP はサイトのURLをSNS(Twitter/FB等)に
張ったときに、コンテンツを展開表示する仕組み
● HTMLのメタタグ の一種で、Webページの内容をSNS
上で表示するための情報を提供する
14
<meta property="og:site_name" content="Sphinx-Users.JP">
<meta property="og:title" content="文字数を表示するPageinfoパネル">
<meta property="og:description" content="記事や本などの原稿を...">
<meta property='og:url' content="http://sphinx-users.jp/xxxx.html">
<meta property="og:image" content="http://sphinx-users/xxxx.png">
OGP タグがサイトに含ま
れていれば、SNSに画像
やコンテンツのテキストを
表示できる
15
og:image
og:description
Facebook postingSpec: http://ogp.me/
og:site_name
og:title
<meta name="twitter:card" content="summary" />
<meta name="twitter:site" content="@sphinxjp" />
<meta property="og:site_name" content="The site title">
<meta property="og:title" content="Title for displaying on TW/FB">
<meta property="og:description" content="blah blah blah ...">
<meta property='og:url' content="http://sphinx-users.jp/index.html">
<meta property="og:image" content="http://sphinx-users/logo.png">
16
TwitterもOGPタグに対応
してますが、Twitterの場合
“twitter:card” と
“twitter:site” タグも提供
する必要がある
og:image
og:description
Tweet
Spec: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/guides/getting-started
og:site_name
og:title
17
SphinxはデフォルトではOGPタグに対応してない
です。
URLをSNSに貼ったら展開されて欲しい
めっちゃ欲しい
で
Sphinx拡張
作りました :) 18
拡張 入門
19
Sphinx拡張入門 (1/3)
Sphinx拡張のエントリーポイントは、 setup() という関数で
す。
今回は `ogtag.py` に `setup` 関数を用意。この関数は、
Sphinx拡張のセットアップをして、メタ情報をリターンします
20
def setup(app):
app.add_config_value('og_site_url', None, 'html')
app.add_config_value('og_twitter_site', None, 'html')
app.connect('html-page-context', html_page_context)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
Spec: http://www.sphinx-doc.org/en/master/extdev/tutorial.html#the-setup-function
ogtag.py
Sphinx拡張入門 (2/3)
setup() 関数内で app.add_config_value() でSphinxに
conf.pyの設定を追加します。
この例では、デフォルト値をNone、値を変えたときは ‘html’ 出
力の場合はフルリビルドするように指定しています。
21
def setup(app):
app.add_config_value('og_site_url', None, 'html')
app.add_config_value('og_twitter_site', None, 'html')
app.connect('html-page-context', html_page_context)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
Spec: http://www.sphinx-doc.org/en/master/extdev/tutorial.html#the-setup-function
og_site_url = ‘http://example.com/’
og_twitter_site = ‘@sphinxjp`
conf.py
ogtag.py
Sphinx拡張入門 (3/3)
app.connect() でイベントハンドラを登録。この例では
html-page-context イベントというHTMLビルド直前のス
テージをフックして、ページ内のデータを収集してogp
metaタグを追加する html_page_context 関数を登録しま
す
22
def setup(app):
app.add_config_value('og_site_url', None, 'html')
app.add_config_value('og_twitter_site', None, 'html')
app.connect('html-page-context', html_page_context)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
Spec: http://www.sphinx-doc.org/en/master/extdev/tutorial.html#the-setup-function
ogtag.py
23
フック関数の動作 (1/4)
html-page-context イベントでogpタグをレンダリングする
ためにdoctreeからデータを集めます。
doctreeはドキュメント(1ファイル)のAST (Abstract Syntax
Tree: 抽象構文木)です。Sphinx拡張はVisitorパターンで
doctreeからデータを集められます。
24
def html_page_context(app, pagename, templatename,
context, doctree):
if not doctree:
return
# walk over the `doctree` structure using visitor pattern
ogtag.py
Spec: http://www.sphinx-doc.org/en/master/extdev/appapi.html#event-html-page-context
フック関数の動作 (2/4)
25
og:image タグのための画像をdoctreeから探します。
imageノードというのをdoctreeから探して1つめを使ってま
す。
class Visitor:
def dispatch_visit(self, node):
…
# collect first image node
if isinstance(node, nodes.image):
self.images.append(node)
…
def get_og_image_url(self, page_url):
if self.images:
return urljoin(page_url, self.images[0]['uri'])
else:
return None
Spec: http://docutils.sourceforge.net/docs/ref/doctree.html
ogtag.py
フック関数の動作 (3/4)
og:descriptionにはページの概要文のためのテキストを持
たせます。この拡張では3セクション分のテキストを集めま
した
26
class Visitor:
def dispatch_visit(self, node):
…
# collect page text from the first 3 sections
if self.n_sections < 3:
# collect text elements
if isinstance(node, nodes.paragraph):
self.text_list.append(node.astext())
…
def get_og_description(self):
text = ' '.join(self.text_list)
if len(text) > 200:
text = text[:197] + '...'
return text
Spec: http://docutils.sourceforge.net/docs/ref/doctree.html
ogtag.py
フック関数の動作 (4/4)
SphinxのHTML出力では context['metatags'] にある
HTMLのメタタグを文字列としてそのまま使います。
この拡張では、そこにogpタグを追加します。
27
def html_page_context(app, pagename, templatename,
context, doctree):
kw = collect_ogp_data(doctree) # collect data fragments
context['metatags'] += ”””
<meta property="og:site_name" content="{sitetitle}">
<meta property="og:title" content="{pagetitle}">
<meta property="og:description" content="{description}">
...snip...
”””.format(**kw)
ogtag.py
Ref: https://github.com/sphinx-doc/sphinx/blob/c307787/sphinx/builders/html.py#L1343
28
make html
29
import sys
import os
sys.path.append(os.path.abspath('_ext')) # path where ogtag.py
extensions = {
‘ogtag’, # python module names of extension
}
og_site_url = 'http://sphinx-users.jp/' # base url path for og:url tag
og_twitter_site = '@sphinxjp' # twitter account for twitter:site.
conf.py
$ make html
…
Build finished. The HTML pages are in _build/html.
$ <deploy _build/html>
command-line
SNSへの投稿を検証
Facebook
● https://developers.facebook.com/tools/debug/sharing/
Twitter
● https://cards-dev.twitter.com/validator
30
31
Next Steps.
● Sphinx拡張の公式チュートリアル
○ http://www.sphinx-doc.org/en/master/extdev/tuto
rial.html
● Sphinx拡張をPyPIで探そう
○ https://pypi.org/search/?q=&o=&c=Framework+
%3A%3A+Sphinx+%3A%3A+Extension
● Sphinx OGP拡張
○ http://sphinx-users.jp/cookbook/ogp/index.html
32
リファレンス
● SphinxでHTMLにOGPタグ出力 - 清水川Web
○ http://www.freia.jp/taka/blog/sphinx-ogp-support/in
dex.html
● Twitter/Facebookへのページシェアでコンテンツを埋
め込む(OGP) -Python製ドキュメンテーションビル
ダー、Sphinxの日本ユーザ会
○ http://sphinx-users.jp/cookbook/ogp/index.html
● OGP
○ http://ogp.me/
33
Questions?
@shimizukawa
34
1 of 34

More Related Content

What's hot(20)

Introduce for sphinx-users-jpIntroduce for sphinx-users-jp
Introduce for sphinx-users-jp
Go Yamada1.5K views
Sphinx GO!!Sphinx GO!!
Sphinx GO!!
Go Yamada909 views
Sphinxの使い方事例Sphinxの使い方事例
Sphinxの使い方事例
Go Yamada13.9K views
Sphinx HTML Theme HacksSphinx HTML Theme Hacks
Sphinx HTML Theme Hacks
Shoji KUMAGAI9K views
APIドキュメントの話 #sphinxjpAPIドキュメントの話 #sphinxjp
APIドキュメントの話 #sphinxjp
Takeshi Komiya10.5K views
ひとりsphinxひとりsphinx
ひとりsphinx
(^-^) togakushi2.4K views
How to spread reST and SphinxHow to spread reST and Sphinx
How to spread reST and Sphinx
Takanori Suzuki8.5K views

Similar to Sphinx customization for OGP support at SphinxCon JP 2018(20)

More from Takayuki Shimizukawa(20)

IKEv2-VPN PyHackCon2023IKEv2-VPN PyHackCon2023
IKEv2-VPN PyHackCon2023
Takayuki Shimizukawa19 views
独学プログラマーのその後独学プログラマーのその後
独学プログラマーのその後
Takayuki Shimizukawa839 views
【修正版】Django + SQLAlchemy: シンプルWay【修正版】Django + SQLAlchemy: シンプルWay
【修正版】Django + SQLAlchemy: シンプルWay
Takayuki Shimizukawa11.2K views

Sphinx customization for OGP support at SphinxCon JP 2018