All docs lead to Sphinx

9ac051aa8b199b55b5da8aeb1679d71d?s=47 Hong Minhee
November 24, 2015

All docs lead to Sphinx

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

9ac051aa8b199b55b5da8aeb1679d71d?s=128

Hong Minhee

November 24, 2015
Tweet

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
  10. None
  11. None
  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.
  16. None
  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