Upgrade to Pro — share decks privately, control downloads, hide ads and more …

All docs lead to Sphinx

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

More Decks by Hong Minhee (洪 民憙)

Other Decks in Programming

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