All docs lead to Sphinx

The slide of All docs lead to Sphinx, a talk presented at SphinxCon JP 2015.

Transcript

1. All docs lead to Sphinx SphinxCon JP 2015 Hong Minhee
2. 洪 ⺠憙 (Hong Minhee) • http://hongminhee.org/ • https://github.com/dahlia • https://twitter.com/hongminhee
3. 洪 ⺠憙 (Hong Minhee) • Works at Spoqa (http://spoqa.jp/) • An enthusiast of F/OSS • Coded in Python since 2005 • Wand, libsass-python
4. 洪 ⺠憙 (Hong Minhee) • A happy user of Sphinx since 2010 • sphinxcontrib-httpdomain • sphinxcontrib-autoprogram
5. Sphinx’s common usages • Tutorials & manuals: plain RST docs • Python API references: sphinx.ext.autodoc • Mostly for Python libraries
6. Not every software is a Python library • Command-line programs: CLI • Microservices: HTTP API
7. HTTP API references • No directives for resources • No roles for methods or status codes • So what are there? • :mailheader: • :mimetype:
8. sphinxcontrib-httpdomain • .. http:get:: • .. http:post:: • :http:header: • :http:statuscode: • and so on
9. 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
12. sphinxcontrib-httpdomain • sphinxcontrib.autohttp.flask • sphinxcontrib.autohttp.bottle • sphinxcontrib.autohttp.tornado • Python domain : sphinx.ext.autodoc
 = httpdomain : sphinxcontrib.autohttp
13. sphinxcontrib.autohttp.flask .. autoflask:: your.micro.service:app :endpoints:
14. Domain for CLI? • Sphinx already provides some for it • .. envvar::, :envvar: • .. program::, :program:, :command: • .. option::, :option:
15. .. 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.
17. sphinxcontrib-autoprogram .. autoprogram:: cli:parser :prog: cli.py
18. Future ideas • Docker images • CSS/Sass/LESS frameworks • Jinja/Mako template macros • Slack commands
19. http://j.mp/sphinxcon-2015-hong