Sphinx customization for OGP support at SphinxCon JP 2018
0 likes3,157 views
Sphinx拡張を作ってSphinxのHTML出力にOGPタグを追加する話です
![フック関数の動作 (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](https://image.slidesharecdn.com/sphinxcustomizationforogpsupportsphinxconjp2018-181128125808/85/Sphinx-customization-for-OGP-support-at-SphinxCon-JP-2018-25-320.jpg)
![フック関数の動作 (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](https://image.slidesharecdn.com/sphinxcustomizationforogpsupportsphinxconjp2018-181128125808/85/Sphinx-customization-for-OGP-support-at-SphinxCon-JP-2018-26-320.jpg)
![フック関数の動作 (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](https://image.slidesharecdn.com/sphinxcustomizationforogpsupportsphinxconjp2018-181128125808/85/Sphinx-customization-for-OGP-support-at-SphinxCon-JP-2018-27-320.jpg)
Sphinx customization for OGP support at SphinxCon JP 2018
- 1. 1
- 2. おまえ誰よ 清水川 貴之 @shimizukawa BeProud, Inc. - connpass, PyQ 一般社団法人PyCon JP - 理事, PyCamp講師 Sphinx - co-maintainer - Sphinx-users.jp 2
- 3. で書いた書籍（ここ 年） 3 2017/10/20 Sphinxをはじめよ う 第2版 2018/2/23 独学プログラマー 2018/6/12 Python プロフェッ ショナルプログラミン グ第3版 2018/2/26 エキスパート Pythonプログラミ ング改訂2版 で書いたよ
- 4. 今日の シャツ 4
- 5. 5
- 6. 翻訳 ● 月1回、週末にSphinxのユーザーと、翻訳する人が集まっ て、各自好きなことをやるイベントです。 ● 参加者はだいたい 4~8人 ● sphinx ● documentation ● translation ● 場所: ● 東京の曙橋・市ヶ谷 6 sphinxjp.connpass.com hack-a-thon
- 7. ● 2018/12/04(火) 19:30 〜 21:30 ● 場所: 市ヶ谷 アルファーロ（イタリアン） ● SphinxのSlackかGoogle Group (ML)に入ってれば参加 OK 総会 忘年会 7 sphinxjp.connpass.com 総会 / 忘年会
- 8. ● 2019/1月？2月？ ● 場所: 国立女性教育会館 （埼玉県 嵐山） ● もくもく 開発合宿 8 sphinxjp.connpass.com 合宿
- 9. 9
- 10. What is Sphinx? Sphinx はドキュメンテーションジェネレーター Sphinxは1つのreSTマークアップのソースから、 複数のファイル形式に出力できます 10 Sphinx reSTreSTreStructuredText (reST) reST Parser HTML Builder ePub Builder LaTeX Builder texlive HTML theme Favorite Editor
- 11. 多くのドキュメントが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
- 12. SPHINX docutils HTML Builder HTML theme (Jinja2) 拡張のメカニズム 12 reST Parser (directive / role) doctree (Intermediate) reSTreST reStructuredText (reST) Sphinx拡張 カスタム記法を追 加 (ディレクティブと ロール) Sphinxのビル ドステージに割 込み And more... 出力形式 の追加 拡張ができることは
- 13. 13
- 14. ● OGP = Open Graph Protocol. ● OGP はサイトのURLをSNS(Twitter/FB等)に 張ったときに、コンテンツを展開表示する仕組み ● HTMLのメタタグ の一種で、Webページの内容をSNS 上で表示するための情報を提供する 14
- 15. <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
- 16. <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. 17
- 19. 拡張 入門 19
- 20. 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
- 21. 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
- 22. 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. 23
- 24. フック関数の動作 (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
- 25. フック関数の動作 (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
- 26. フック関数の動作 (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
- 27. フック関数の動作 (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. 28
- 29. 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
- 31. 31
- 32. 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
- 33. リファレンス ● 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