Why we need to learn

“Inside Sphinx”

Takeshi KOMIYA (@tk0miya)

2019.11.25 @ SphinxCon JP 2019

↓ URL of this slide

Who am I ?

• Takeshi KOMIYA
• @tk0miya
• CTO of TIME INTERMEDIA, Inc.
• We’re hiring!
• OSS Developer
• Sphinx
• Sphinx extensions
• blockdiag
• Winner of Open Source

Bonus Program (Oct, 2017)

Who am I ?

• blockdiag: Generate graph image from text

{

"Top page" -> "Sign in" -> "My Page";

"Top page" -> "List page" -> "Detail page";

}

Who am I ? (Books, Articles)

• Books and magazines
• Getting Started Sphinx (2nd edition)
• Software Design (2015/4~2017/3, with friends)
• teckbookfest (技術書典7, き42D)

Who am I ?

• As a maintainer of Sphinx
• 2000+ contributions in last 12months
• Most active committer in the world
• I’ve producted 50-60% of commits.

Agenda

• Extensions I’ve ever made
• Why extension needed
• To make own Sphinx extension
• Conclusion

​

Agenda

• Extensions I’ve ever made
• Why extension needed
• To make own Sphinx extension
• Conclusion

​

Extensions I’ve ever made

• Ever I’ve made tons of Sphinx exts
• 26 packages on PyPI
• 28 micro posts to Gist
• quick hacks
• seeds of new extensions

​

Extensions I’ve ever made

• sphinxcontrib-cacoo
• Fetch and embed a remote image
• similars: astah, googledrive

​

source

Image

on

Cacoo

Fetch image

from Cacoo

Extensions I’ve ever made

• sphinxcontrib-astah
• Convert embed an astah*’s image
• similars: visio

​

source

Convert image

astah*’s

image

Extensions I’ve ever made

• sphinxcontrib-apiblueprint
• Convert and embed a local file
• similars: jsonschema

​

source

API

Blueprint

Definition

Convert API def.

to document

Extensions I’ve ever made

• sphinxcontrib-commonmark
• Allow to use another format as a source
• will support GFM in future (if requested)
• similars: toc

​

​

Extensions I’ve ever made

• sphinxcontrib-getstart-sphinx
• Gather footnotes to bottom of each section
• similars: bibliography

​

source

Modifies

doc structure

Extensions I’ve ever made

• sphinxcontrib-details-directive
• Generate <details> tag in HTML output
• similars: emoji

​

source

<details>

Extensions I’ve ever made

• sphinxcontrib-googlemaps
• Embed a content on internet to document
• similars:
• slide, googlechart, nicovideo
• remoteinclude

​

source

Google

Maps

Extensions I’ve ever made

• schema2rst
• Generate .rst file from live database
• autodoc for database

​

source

DB

Agenda

• Extensions I’ve ever made
• Why extension needed
• To make own Sphinx extension
• Conclusion

​

Why extensions needed?

• Automation
• Representation for specific output format
• Collaborate with external tools & services
• Arrange document structure
• Add a new feature

​

Why extensions needed?

• Automation
• Let computer working instead of you
• Case of cacoo ext.
• Before:
• Edit image → Export → Build docs → Edit …
• After:
• Edit image → Build docs

Why extensions needed?

• Representation for specific output format
• Sphinx-core only provides commonly used document-structure as a parts
• Video, Slides, Maps are not provided
• Hard to represent except in HTML
• Case of details-directive
• Allows to use <details> tag on HTML build
• Contents are expanded in other output

Why extensions needed?

• Collaborate with external tools & services
• There are many useful services for docs
• ex. drawing tools
• Everything it can be converted to docs
• Infrastructure as Code
• Open API Specification
• Case of sphinxcontrib-cacoo
• Embed a diagram drawn in Cacoo
• Only build to use, no additional operations!

Why extensions needed?

• Arrange document structure
• Rewrite and modify document structure
• Relocate elements
• Change styles
• Case of sphinx-getstart-sphinx
• Relocate footnotes to end of each section
• It is useful for EPUB output
• Before
• footnotes are shown at written location
• After
• footnotes are shown at end of section

Why extensions needed?

• Add a new feature
• sphinxcontrib-commonmark
• brandnew custom commonmark parser
• follows commonmark spec perfectly
• Allow to enhance syntax via code
• I’ll support GitHub Flavored Markdown in future

Why extensions needed?

• Making own ext. is not special
• It’s like a macro for documentation
• It makes your documentation better

​

Agenda

• Extensions I’ve ever made
• Why extension needed
• To make own Sphinx extension
• Conclusion

​

To make own Sphinx extension

• How to make own Sphinx extension?
• Recipes:
• Python code
• docutils
• Sphinx Framework & API
• Case of Sphinx extensions

To make own Sphinx extension

• How to get knowledges for development
• Sources
• sphinx documentation
• source code
• sphinx-core
• other extensions
• community
• sphinx-users group (EN)
• sphinx-users.jp (JA)

To make own Sphinx extension

• How to get knowledges for development
• Sources
• books
• mastering docutils (JA)
• Inside Sphinx (JA)

To make own Sphinx extension

• Inside Sphinx
• Learn how to develop ext. via 4 examples
• How to enhance reST markup
• sphinxcontrib-textstyle
• How to add own configurations
• sphinx.ext.graphviz
• How to hook Sphinx events
• sphinx.ext.githubpages
• How to modify document structures
• sphinxcontrib-getstart-sphinx

​

• I’ll contiue to ship next book if requested :-)

Agenda

• Extensions I’ve ever made
• Why extension needed
• To make own Sphinx extension
• Conclusion

​

Conclusion

• Sphinx extension is your friends
• It’s like a macro, not a special tool
• Pick up for your writing environment
• Let’s make new one if not found
• Learning what ext. can do
• Knowledge of ext will help your development
• There are many sources

AD: personal sponsorship

• I started personal sponsorship program to support my OSS development
• It’s very helpful to me if you become my sponsor!
• Thank you for my sponsors!

​

For Japanese readers

For English readers

emoji extension

• I wrote a new (joke) extension at last week
• https://twitter.com/tk0miya/status/1196445903785058310

upLaTeX support

• Add upLaTeX support to core
• Stay tuned
• ​

​

​

​

​

​

• Issues and questions are important. They are seeds of my development. Don’t be shy!