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
   

   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