Sphinx REST api

.travis.yml

@@ -43,6 +43,6 @@ before_script:
 script:
     - 'if [[ -z $TEST_SUITE ]]; then sleep 10; python setup.py test; return $?; fi'
     - 'if [[ $TEST_SUITE == flake ]]; then flake8; return $?; fi'
-    - 'if [[ $TEST_SUITE == build_sphinx ]]; then python setup.py build_sphinx; return $?; fi'
+    - 'if [[ $TEST_SUITE == build_sphinx ]]; then pip install ".[doc]" && python setup.py build_sphinx; return $?; fi'
 
 cache: pip

doc/source/conf.py

@@ -33,6 +33,15 @@
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
 ]
+try:
+    import sphinxcontrib.autohttp.flask
+except ImportError:
+    print "WARNING: sphinxcontrib-httpdomain not installed," \
+        "you will get no REST API doc"
+    print "  You might want to do pip install -U pip && pip install '.[doc]'"
+else:
+    del sphinxcontrib.autohttp.flask
+    extensions += ['sphinxcontrib.autohttp.flask']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/source/documentation.rst

@@ -27,7 +27,7 @@ which to include all the other pages.
         add its filename to the ``toctree`` in ``index.rst``
 
 To build html documentation from it, you should first of all ``pip install
-Sphinx`` inside your virtualenv. Then you can run ``python setup.py
+'.[doc]'`` inside your virtualenv. If this command fails, you probably have an old pip version: run ``pip install -U pip`` to fix this. Then you can run ``python setup.py
 build_sphinx``. This command will create documentation inside
 ``build/sphinx/html/``. So run ``firefox build/sphinx/html/index.html`` and you
 can read it.

doc/source/httpapi.rst

@@ -0,0 +1,16 @@
+HTTP API
+=========
+
+Archivant and Users
+---------------------
+
+.. autoflask:: webant.webant:create_app(dict(USERS_DATABASE='sqlite:////tmp/asd'))
+   :blueprints: api
+   :include-empty-docstring:
+
+Agherant
+-----------
+
+.. autoflask:: webant.webant:create_app(dict(AGHERANT_DESCRIPTIONS=range(3)))
+   :blueprints: agherant
+   :include-empty-docstring:

doc/source/index.rst

@@ -17,6 +17,7 @@ Contents:
    sysadmin
    documentation
    developer
+   httpapi
    api/modules
 
 

setup.py

@@ -123,6 +123,9 @@ def read(fname):
           'webant': ['translations/*/*/*.mo']
         },
         include_package_data=True,
+        extras_require={
+            'doc':['sphinx', 'sphinxcontrib-httpdomain>=1.1'],
+        },
         tests_require=['nose', 'coverage'],
         zip_safe=False,
         cmdclass={'build': build,