Slide 1
Slide 1 text
All docs lead to Sphinx
SphinxCon JP 2015
Hong Minhee
Slide 2
Slide 2 text
洪 ⺠憙 (Hong Minhee)
• http://hongminhee.org/
• https://github.com/dahlia
• https://twitter.com/hongminhee
Slide 3
Slide 3 text
洪 ⺠憙 (Hong Minhee)
• Works at Spoqa (http://spoqa.jp/)
• An enthusiast of F/OSS
• Coded in Python since 2005
• Wand, libsass-python
Slide 4
Slide 4 text
洪 ⺠憙 (Hong Minhee)
• A happy user of Sphinx since 2010
• sphinxcontrib-httpdomain
• sphinxcontrib-autoprogram
Slide 5
Slide 5 text
Sphinx’s common usages
• Tutorials & manuals: plain RST docs
• Python API references: sphinx.ext.autodoc
• Mostly for Python libraries
Slide 6
Slide 6 text
Not every software is a Python library
• Command-line programs: CLI
• Microservices: HTTP API
Slide 7
Slide 7 text
HTTP API references
• No directives for resources
• No roles for methods or status codes
• So what are there?
• :mailheader:
• :mimetype:
Slide 8
Slide 8 text
sphinxcontrib-httpdomain
• .. http:get::
• .. http:post::
• :http:header:
• :http:statuscode:
• and so on
Slide 9
Slide 9 text
sphinxcontrib-httpdomain
.. http:get:: /users/(int:user_id)/posts/(tag)
The posts tagged with `tag` that the user (`user_id`) wrote.
:query sort: one of ``hit``, ``created-at``
:query offset: offset number. default is 0
:query limit: limit number. default is 30
:reqheader Authorization: optional OAuth token to authenticate
:statuscode 200: no error
:statuscode 404: there's no user
Slide 10
Slide 10 text
No content
Slide 11
Slide 11 text
No content
Slide 12
Slide 12 text
sphinxcontrib-httpdomain
• sphinxcontrib.autohttp.flask
• sphinxcontrib.autohttp.bottle
• sphinxcontrib.autohttp.tornado
• Python domain : sphinx.ext.autodoc
= httpdomain : sphinxcontrib.autohttp
Slide 13
Slide 13 text
sphinxcontrib.autohttp.flask
.. autoflask:: your.micro.service:app
:endpoints:
Slide 14
Slide 14 text
Domain for CLI?
• Sphinx already provides some for it
• .. envvar::, :envvar:
• .. program::, :program:, :command:
• .. option::, :option:
Slide 15
Slide 15 text
.. program:: sassc
.. option:: -m, -g, --sourcemap
Emit source map. The filename of source map will be the output CSS
filename followed by :file:`.map`.
.. option:: -w, --watch
Watch file for changes. Requires the second argument (output CSS
filename).
.. option:: -p, --precision
Set the precision for numbers. Default is 5.
Slide 16
Slide 16 text
No content
Slide 17
Slide 17 text
sphinxcontrib-autoprogram
.. autoprogram:: cli:parser
:prog: cli.py
Slide 18
Slide 18 text
Future ideas
• Docker images
• CSS/Sass/LESS frameworks
• Jinja/Mako template macros
• Slack commands
Slide 19
Slide 19 text
http://j.mp/sphinxcon-2015-hong