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.

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

    View Slide

  2. 洪 ⺠憙 (Hong Minhee)
    • http://hongminhee.org/
    • https://github.com/dahlia
    • https://twitter.com/hongminhee

    View Slide

  3. 洪 ⺠憙 (Hong Minhee)
    • Works at Spoqa (http://spoqa.jp/)
    • An enthusiast of F/OSS
    • Coded in Python since 2005
    • Wand, libsass-python

    View Slide

  4. 洪 ⺠憙 (Hong Minhee)
    • A happy user of Sphinx since 2010
    • sphinxcontrib-httpdomain
    • sphinxcontrib-autoprogram

    View Slide

  5. Sphinx’s common usages
    • Tutorials & manuals: plain RST docs
    • Python API references: sphinx.ext.autodoc
    • Mostly for Python libraries

    View Slide

  6. Not every software is a Python library
    • Command-line programs: CLI
    • Microservices: HTTP API

    View Slide

  7. HTTP API references
    • No directives for resources
    • No roles for methods or status codes
    • So what are there?
    • :mailheader:
    • :mimetype:

    View Slide

  8. sphinxcontrib-httpdomain
    • .. http:get::
    • .. http:post::
    • :http:header:
    • :http:statuscode:
    • and so on

    View Slide

  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

    View Slide

  10. View Slide

  11. View Slide

  12. sphinxcontrib-httpdomain
    • sphinxcontrib.autohttp.flask
    • sphinxcontrib.autohttp.bottle
    • sphinxcontrib.autohttp.tornado
    • Python domain : sphinx.ext.autodoc

    = httpdomain : sphinxcontrib.autohttp

    View Slide

  13. sphinxcontrib.autohttp.flask
    .. autoflask:: your.micro.service:app
    :endpoints:

    View Slide

  14. Domain for CLI?
    • Sphinx already provides some for it
    • .. envvar::, :envvar:
    • .. program::, :program:, :command:
    • .. option::, :option:

    View Slide

  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.

    View Slide

  16. View Slide

  17. sphinxcontrib-autoprogram
    .. autoprogram:: cli:parser
    :prog: cli.py

    View Slide

  18. Future ideas
    • Docker images
    • CSS/Sass/LESS frameworks
    • Jinja/Mako template macros
    • Slack commands

    View Slide

  19. http://j.mp/sphinxcon-2015-hong

    View Slide