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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

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

    = httpdomain : sphinxcontrib.autohttp

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  13. .. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide