Sphinx customization for OGP support at SphinxCon JP 2018
•
0 likes•2,968 views
Sphinx拡張を作ってSphinxのHTML出力にOGPタグを追加する話です
Recommended
More Related Content
What's hot
What's hot (20)
Similar to Sphinx customization for OGP support at SphinxCon JP 2018
Similar to Sphinx customization for OGP support at SphinxCon JP 2018 (20)
More from Takayuki Shimizukawa
More from Takayuki Shimizukawa (20)
Recently uploaded
Recently uploaded (9)
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