Automatically document the REST API with cornice.

fixes #1323 Signed-off-by: Randy Barlow <randy@electronsweatshop.com>
fedora-infra · Mar 8, 2017 · 72c9895 · 72c9895
1 parent f38b96d
commit 72c9895
Show file tree

Hide file tree

Showing 15 changed files with 85 additions and 16 deletions.
diff --git a/devel/ansible/roles/dev/tasks/main.yml b/devel/ansible/roles/dev/tasks/main.yml
@@ -25,6 +25,7 @@
       - python-bunch
       - python-click
       - python-cornice
+      - python-cornice-sphinx
       - python-devel
       - python-dogpile-cache
       - python-fedora

diff --git a/docs/conf.py b/docs/conf.py
@@ -19,6 +19,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '../')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), 'rtd_hacks')))
 
 # -- General configuration -----------------------------------------------------
 
@@ -27,7 +28,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc',
+extensions = ['cornice.ext.sphinxext', 'sphinx.ext.autodoc',
               'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode']
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/index.rst b/docs/index.rst
@@ -15,7 +15,7 @@ Contents:
    man_pages/index
    python_bindings
    developer_docs
-   services
+   rest_api/index
    release_notes
 
 

diff --git a/docs/rest_api/builds.rst b/docs/rest_api/builds.rst
@@ -0,0 +1,6 @@
+Builds
+======
+
+.. cornice-autodoc::
+   :modules: bodhi.server.services.builds
+   :services: build, builds
diff --git a/docs/rest_api/comments.rst b/docs/rest_api/comments.rst
@@ -0,0 +1,6 @@
+Comments
+========
+
+.. cornice-autodoc::
+   :modules: bodhi.server.services.comments
+   :services: comment, comments, comments_rss
diff --git a/docs/rest_api/csrf.rst b/docs/rest_api/csrf.rst
@@ -0,0 +1,6 @@
+CSRF
+====
+
+.. cornice-autodoc::
+   :modules: bodhi.server.services.csrf
+   :services: csrf
diff --git a/docs/rest_api/index.rst b/docs/rest_api/index.rst
@@ -0,0 +1,20 @@
+Bodhi REST API
+==============
+
+This section of the documentation describes Bodhi's REST API. You can read about the various
+sections of the API by following the links below:
+
+
+.. toctree::
+   :maxdepth: 2
+
+   builds
+   comments
+   csrf
+   markdown
+   overrides
+   packages
+   releases
+   stacks
+   updates
+   users
diff --git a/docs/rest_api/markdown.rst b/docs/rest_api/markdown.rst
@@ -0,0 +1,6 @@
+Markdown
+========
+
+.. cornice-autodoc::
+   :modules: bodhi.server.services.markdown
+   :services: markdowner
diff --git a/docs/rest_api/overrides.rst b/docs/rest_api/overrides.rst
@@ -0,0 +1,7 @@
+Overrides
+=========
+
+
+.. cornice-autodoc::
+   :modules: bodhi.server.services.overrides
+   :services: override, overrides, overrides_rss
diff --git a/docs/rest_api/packages.rst b/docs/rest_api/packages.rst
@@ -0,0 +1,6 @@
+Packages
+========
+
+.. cornice-autodoc::
+   :modules: bodhi.server.services.packages
+   :services: packages
diff --git a/docs/rest_api/releases.rst b/docs/rest_api/releases.rst
@@ -0,0 +1,6 @@
+Releases
+========
+
+.. cornice-autodoc::
+   :modules: bodhi.server.services.releases
+   :services: release, releases
diff --git a/docs/rest_api/stacks.rst b/docs/rest_api/stacks.rst
@@ -0,0 +1,6 @@
+Stacks
+======
+
+.. cornice-autodoc::
+   :modules: bodhi.server.services.stacks
+   :services: stack, stacks
diff --git a/docs/rest_api/updates.rst b/docs/rest_api/updates.rst
@@ -0,0 +1,6 @@
+Updates
+=======
+
+.. cornice-autodoc::
+   :modules: bodhi.server.services.updates, bodhi.server.services.zz_redirects
+   :services: bodhi1_update_redirect, update, update_edit, update_request, updates, updates_rss
diff --git a/docs/rest_api/users.rst b/docs/rest_api/users.rst
@@ -0,0 +1,6 @@
+Users
+=====
+
+.. cornice-autodoc::
+   :modules: bodhi.server.services.user
+   :services: user, users, users_rss
diff --git a/docs/services.rst b/docs/services.rst