1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
Document your API
=================
Web services without a proper documentation are usually useless.
To make it easy to document your own API, WSME provides a Sphinx_ extension.
Install the extension
---------------------
Here we consider that you already quick-started a sphinx project.
#. In your ``conf.py`` file, add ``'ext'`` to you extensions,
and optionally set the enabled protocols.
.. code-block:: python
extensions = ['ext']
wsme_protocols = ['restjson', 'restxml', 'extdirect']
#. Copy :download:`toggle.js <_static/toggle.js>`
and :download:`toggle.css <_static/toggle.css>`
in your _static directory.
The ``wsme`` domain
-------------------
The extension will add a new Sphinx domain providing a few directives.
Config values
~~~~~~~~~~~~~
.. confval:: wsme_protocols
A list of strings that are WSME protocol names. If provided by an
additionnal package (for example WSME-Soap or WSME-ExtDirect), it must
be installed.
The types and services generated documentation will include code samples
for each of these protocols.
.. confval:: wsme_root
A string that is the full name of the service root controller.
It will be used
to determinate the relative path of the other controllers when they
are autodocumented, and calculate the complete webpath of the other
controllers.
.. confval:: wsme_webpath
A string that is the webpath where the :confval:`wsme_root` is mounted.
Directives
~~~~~~~~~~
.. rst:directive:: .. root:: <WSRoot full path>
Allow to define the service root controller in one documentation source file.
To set it globally, see :confval:`wsme_root`.
A ``webpath`` option allow to override :confval:`wsme_webpath`.
Example:
.. code-block:: rst
.. wsme:root:: myapp.controllers.MyWSRoot
:webpath: /api
.. rst:directive:: .. service:: name/space/ServiceName
Declare a service.
.. rst:directive:: .. type:: MyComplexType
Equivalent to the :rst:dir:`py:class` directive to document a complex type
.. rst:directive:: .. attribute:: aname
Equivalent to the :rst:dir:`py:attribute` directive to document a complex type
attribute. It takes an additionnal ``:type:`` field.
Example
~~~~~~~
.. list-table::
:header-rows: 1
* - Source
- Result
* - .. code-block:: rst
.. wsme:root:: wsmeext.sphinxext.SampleService
:webpath: /api
.. wsme:type:: MyType
.. wsme:attribute:: test
:type: int
.. wsme:service:: name/space/SampleService
.. wsme:function:: doit
- .. wsme:root:: wsmeext.sphinxext.SampleService
:webpath: /api
.. wsme:type:: MyType
.. wsme:attribute:: test
:type: int
.. wsme:service:: name/space/SampleService
.. wsme:function:: getType
Returns a :wsme:type:`MyType <MyType>`
Autodoc directives
~~~~~~~~~~~~~~~~~~
Theses directives scan your code to generate the documentation from the
docstrings and your API types and controllers.
.. rst:directive:: .. autotype:: myapp.MyType
Generate the myapp.MyType documentation.
.. rst:directive:: .. autoattribute:: myapp.MyType.aname
Generate the myapp.MyType.aname documentation.
.. rst:directive:: .. autoservice:: myapp.MyService
Generate the myapp.MyService documentation.
.. rst:directive:: .. autofunction:: myapp.MyService.myfunction
Generate the myapp.MyService.myfunction documentation.
Full Example
------------
Python source
~~~~~~~~~~~~~
.. literalinclude:: ../wsmeext/sphinxext.py
:lines: 42-67
:language: python
Documentation source
~~~~~~~~~~~~~~~~~~~~
.. code-block:: rst
.. default-domain:: wsmeext
.. autotype:: wsmeext.sphinxext.SampleType
:members:
.. autoservice:: wsmeext.sphinxext.SampleService
:members:
Result
~~~~~~
.. default-domain:: wsmeext
.. type:: int
An integer
.. autotype:: wsmeext.sphinxext.SampleType
:members:
.. autoservice:: wsmeext.sphinxext.SampleService
:members:
.. _Sphinx: http://sphinx.pocoo.org/
|
