Fix documentation generation

docs/api/examples/post_project.txt

@@ -1,8 +1,8 @@
-curl -i -X POST 'http://localhost:8000/project' -d '{"location": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-321/test_create_project_with_dir0"}'
+curl -i -X POST 'http://localhost:8000/project' -d '{"location": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-328/test_create_project_with_dir0"}'
 
 POST /project HTTP/1.1
 {
-    "location": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-321/test_create_project_with_dir0"
+    "location": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-328/test_create_project_with_dir0"
 }
 
 
@@ -15,6 +15,6 @@ SERVER: Python/3.4 aiohttp/0.13.1
 X-ROUTE: /project
 
 {
-    "location": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-321/test_create_project_with_dir0",
+    "location": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-328/test_create_project_with_dir0",
-    "uuid": "a00bbbdf-4088-4634-816d-513e0428275f"
+    "uuid": "b4432fe3-6743-4ce7-ab05-1f5637d04cd6"
 }

docs/api/project.rst

@@ -0,0 +1,39 @@
+/project
+---------------------------------------------
+
+.. contents::
+
+POST /project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Create a project on the server
+
+Response status codes
+**********************
+- **200**: OK
+
+Input
+*******
+.. raw:: html
+
+    <table>
+    <tr>                 <th>Name</th>                 <th>Mandatory</th>                 <th>Type</th>                 <th>Description</th>                 </tr>
+    <tr><td>location</td>                    <td> </td>                     <td>string</td>                     <td>Base directory where the project should be created on remote server</td>                     </tr>
+    <tr><td>uuid</td>                    <td> </td>                     <td>string</td>                     <td>Project UUID</td>                     </tr>
+    </table>
+
+Output
+*******
+.. raw:: html
+
+    <table>
+    <tr>                 <th>Name</th>                 <th>Mandatory</th>                 <th>Type</th>                 <th>Description</th>                 </tr>
+    <tr><td>location</td>                    <td> </td>                     <td>string</td>                     <td>Base directory where the project should be created on remote server</td>                     </tr>
+    <tr><td>uuid</td>                    <td> </td>                     <td>string</td>                     <td>Project UUID</td>                     </tr>
+    </table>
+
+Sample session
+***************
+
+
+.. literalinclude:: examples/post_project.txt
+

docs/api/version.rst

@@ -1,14 +1,14 @@
 /version
-------------------------------
+---------------------------------------------
 
 .. contents::
 
 GET /version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Retrieve server version number
+Retrieve the server version number
 
 Response status codes
-**************************
+**********************
 - **200**: OK
 
 Output
@@ -16,8 +16,8 @@ Output
 .. raw:: html
 
     <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
+    <tr>                 <th>Name</th>                 <th>Mandatory</th>                 <th>Type</th>                 <th>Description</th>                 </tr>
-    <tr><td>version</td><td>&#10004;</td><td>string</td><td>Version number human readable</td></tr>
+    <tr><td>version</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>Version number human readable</td>                     </tr>
     </table>
 
 Sample session
@@ -26,3 +26,37 @@ Sample session
 
 .. literalinclude:: examples/get_version.txt
 
+
+POST /version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Check if version is the same as the server
+
+Response status codes
+**********************
+- **200**: Same version
+- **409**: Invalid version
+
+Input
+*******
+.. raw:: html
+
+    <table>
+    <tr>                 <th>Name</th>                 <th>Mandatory</th>                 <th>Type</th>                 <th>Description</th>                 </tr>
+    <tr><td>version</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>Version number human readable</td>                     </tr>
+    </table>
+
+Output
+*******
+.. raw:: html
+
+    <table>
+    <tr>                 <th>Name</th>                 <th>Mandatory</th>                 <th>Type</th>                 <th>Description</th>                 </tr>
+    <tr><td>version</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>Version number human readable</td>                     </tr>
+    </table>
+
+Sample session
+***************
+
+
+.. literalinclude:: examples/post_version.txt
+

docs/api/vpcs.rst

@@ -1,19 +1,15 @@
 /vpcs
-------------------------------
+---------------------------------------------
 
 .. contents::
 
 POST /vpcs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Create a new VPCS and return it
+Create a new VPCS instance
-
-Parameters
-**********
-- **vpcs_id**: Id of VPCS instance
 
 Response status codes
-**************************
+**********************
-- **201**: Success of creation of VPCS
+- **201**: VPCS instance created
 - **409**: Conflict
 
 Input
@@ -21,10 +17,12 @@ Input
 .. raw:: html
 
     <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
+    <tr>                 <th>Name</th>                 <th>Mandatory</th>                 <th>Type</th>                 <th>Description</th>                 </tr>
-    <tr><td>console</td><td> </td><td>integer</td><td>console TCP port</td></tr>
+    <tr><td>console</td>                    <td> </td>                     <td>integer</td>                     <td>console TCP port</td>                     </tr>
-    <tr><td>name</td><td>&#10004;</td><td>string</td><td>VPCS device name</td></tr>
+    <tr><td>name</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>VPCS device name</td>                     </tr>
-    <tr><td>vpcs_id</td><td> </td><td>integer</td><td>VPCS device instance ID</td></tr>
+    <tr><td>project_uuid</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>Project UUID</td>                     </tr>
+    <tr><td>uuid</td>                    <td> </td>                     <td>string</td>                     <td>VPCS device UUID</td>                     </tr>
+    <tr><td>vpcs_id</td>                    <td> </td>                     <td>integer</td>                     <td>VPCS device instance ID (for project created before GNS3 1.3)</td>                     </tr>
     </table>
 
 Output
@@ -32,10 +30,11 @@ Output
 .. raw:: html
 
     <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
+    <tr>                 <th>Name</th>                 <th>Mandatory</th>                 <th>Type</th>                 <th>Description</th>                 </tr>
-    <tr><td>console</td><td>&#10004;</td><td>integer</td><td>console TCP port</td></tr>
+    <tr><td>console</td>                    <td>&#10004;</td>                     <td>integer</td>                     <td>console TCP port</td>                     </tr>
-    <tr><td>name</td><td>&#10004;</td><td>string</td><td>VPCS device name</td></tr>
+    <tr><td>name</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>VPCS device name</td>                     </tr>
-    <tr><td>vpcs_id</td><td>&#10004;</td><td>integer</td><td>VPCS device instance ID</td></tr>
+    <tr><td>project_uuid</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>Project UUID</td>                     </tr>
+    <tr><td>uuid</td>                    <td>&#10004;</td>                     <td>string</td>                     <td>VPCS device UUID</td>                     </tr>
     </table>
 
 Sample session

docs/api/vpcsuuidportsportidnio.rst

@@ -0,0 +1,48 @@
+/vpcs/{uuid}/ports/{port_id}/nio
+---------------------------------------------
+
+.. contents::
+
+POST /vpcs/{uuid}/ports/{port_id}/nio
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Add a NIO to a VPCS
+
+Parameters
+**********
+- **port_id**: Id of the port where the nio should be add
+- **uuid**: VPCS instance UUID
+
+Response status codes
+**********************
+- **400**: Invalid VPCS instance UUID
+- **201**: NIO created
+- **404**: VPCS instance doesn't exist
+
+Sample session
+***************
+
+
+.. literalinclude:: examples/post_vpcsuuidportsportidnio.txt
+
+
+DELETE /vpcs/{uuid}/ports/{port_id}/nio
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Remove a NIO from a VPCS
+
+Parameters
+**********
+- **port_id**: ID of the port where the nio should be removed
+- **uuid**: VPCS instance UUID
+
+Response status codes
+**********************
+- **200**: NIO deleted
+- **400**: Invalid VPCS instance UUID
+- **404**: VPCS instance doesn't exist
+
+Sample session
+***************
+
+
+.. literalinclude:: examples/delete_vpcsuuidportsportidnio.txt
+

docs/api/vpcsuuidstart.rst

@@ -0,0 +1,19 @@
+/vpcs/{uuid}/start
+---------------------------------------------
+
+.. contents::
+
+POST /vpcs/{uuid}/start
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Start a VPCS instance
+
+Parameters
+**********
+- **uuid**: VPCS instance UUID
+
+Response status codes
+**********************
+- **400**: Invalid VPCS instance UUID
+- **404**: VPCS instance doesn't exist
+- **204**: VPCS instance started
+

docs/api/vpcsuuidstop.rst

@@ -0,0 +1,19 @@
+/vpcs/{uuid}/stop
+---------------------------------------------
+
+.. contents::
+
+POST /vpcs/{uuid}/stop
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Stop a VPCS instance
+
+Parameters
+**********
+- **uuid**: VPCS instance UUID
+
+Response status codes
+**********************
+- **400**: Invalid VPCS instance UUID
+- **404**: VPCS instance doesn't exist
+- **204**: VPCS instance stopped
+

docs/api/vpcsvpcsid.rst

@@ -1,63 +0,0 @@
-/vpcs/{vpcs_id}
-------------------------------
-
-.. contents::
-
-GET /vpcs/{vpcs_id}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Get informations about a VPCS
-
-Parameters
-**********
-- **vpcs_id**: Id of VPCS instance
-
-Response status codes
-**************************
-- **200**: OK
-
-Output
-*******
-.. raw:: html
-
-    <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
-    <tr><td>console</td><td>&#10004;</td><td>integer</td><td>console TCP port</td></tr>
-    <tr><td>name</td><td>&#10004;</td><td>string</td><td>VPCS device name</td></tr>
-    <tr><td>vpcs_id</td><td>&#10004;</td><td>integer</td><td>VPCS device instance ID</td></tr>
-    </table>
-
-
-PUT /vpcs/{vpcs_id}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Update VPCS informations
-
-Parameters
-**********
-- **vpcs_id**: Id of VPCS instance
-
-Response status codes
-**************************
-- **200**: OK
-
-Input
-*******
-.. raw:: html
-
-    <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
-    <tr><td>console</td><td>&#10004;</td><td>integer</td><td>console TCP port</td></tr>
-    <tr><td>name</td><td>&#10004;</td><td>string</td><td>VPCS device name</td></tr>
-    <tr><td>vpcs_id</td><td>&#10004;</td><td>integer</td><td>VPCS device instance ID</td></tr>
-    </table>
-
-Output
-*******
-.. raw:: html
-
-    <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
-    <tr><td>console</td><td>&#10004;</td><td>integer</td><td>console TCP port</td></tr>
-    <tr><td>name</td><td>&#10004;</td><td>string</td><td>VPCS device name</td></tr>
-    <tr><td>vpcs_id</td><td>&#10004;</td><td>integer</td><td>VPCS device instance ID</td></tr>
-    </table>
-

docs/api/vpcsvpcsidnio.rst

@@ -1,127 +0,0 @@
-/vpcs/{vpcs_id}/nio
-------------------------------
-
-.. contents::
-
-POST /vpcs/{vpcs_id}/nio
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-ADD NIO to a VPCS
-
-Parameters
-**********
-- **vpcs_id**: Id of VPCS instance
-
-Response status codes
-**************************
-- **201**: Success of creation of NIO
-- **409**: Conflict
-
-Input
-*******
-Types
-+++++++++
-Ethernet
-^^^^^^^^^^^^^^^^
-Generic Ethernet Network Input/Output
-
-.. raw:: html
-
-    <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
-    <tr><td>ethernet_device</td><td>&#10004;</td><td>string</td><td>Ethernet device name e.g. eth0</td></tr>
-    <tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_generic_ethernet</td></tr>
-    </table>
-
-LinuxEthernet
-^^^^^^^^^^^^^^^^
-Linux Ethernet Network Input/Output
-
-.. raw:: html
-
-    <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
-    <tr><td>ethernet_device</td><td>&#10004;</td><td>string</td><td>Ethernet device name e.g. eth0</td></tr>
-    <tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_linux_ethernet</td></tr>
-    </table>
-
-NULL
-^^^^^^^^^^^^^^^^
-NULL Network Input/Output
-
-.. raw:: html
-
-    <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
-    <tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_null</td></tr>
-    </table>
-
-TAP
-^^^^^^^^^^^^^^^^
-TAP Network Input/Output
-
-.. raw:: html
-
-    <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
-    <tr><td>tap_device</td><td>&#10004;</td><td>string</td><td>TAP device name e.g. tap0</td></tr>
-    <tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_tap</td></tr>
-    </table>
-
-UDP
-^^^^^^^^^^^^^^^^
-UDP Network Input/Output
-
-.. raw:: html
-
-    <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
-    <tr><td>lport</td><td>&#10004;</td><td>integer</td><td>Local port</td></tr>
-    <tr><td>rhost</td><td>&#10004;</td><td>string</td><td>Remote host</td></tr>
-    <tr><td>rport</td><td>&#10004;</td><td>integer</td><td>Remote port</td></tr>
-    <tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_udp</td></tr>
-    </table>
-
-UNIX
-^^^^^^^^^^^^^^^^
-UNIX Network Input/Output
-
-.. raw:: html
-
-    <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
-    <tr><td>local_file</td><td>&#10004;</td><td>string</td><td>path to the UNIX socket file (local)</td></tr>
-    <tr><td>remote_file</td><td>&#10004;</td><td>string</td><td>path to the UNIX socket file (remote)</td></tr>
-    <tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_unix</td></tr>
-    </table>
-
-VDE
-^^^^^^^^^^^^^^^^
-VDE Network Input/Output
-
-.. raw:: html
-
-    <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
-    <tr><td>control_file</td><td>&#10004;</td><td>string</td><td>path to the VDE control file</td></tr>
-    <tr><td>local_file</td><td>&#10004;</td><td>string</td><td>path to the VDE control file</td></tr>
-    <tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_vde</td></tr>
-    </table>
-
-Body
-+++++++++
-.. raw:: html
-
-    <table>
-    <tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
-    <tr><td>id</td><td>&#10004;</td><td>integer</td><td>VPCS device instance ID</td></tr>
-    <tr><td>nio</td><td>&#10004;</td><td>UDP, Ethernet, LinuxEthernet, TAP, UNIX, VDE, NULL</td><td>Network Input/Output</td></tr>
-    <tr><td>port</td><td>&#10004;</td><td>integer</td><td>Port number</td></tr>
-    <tr><td>port_id</td><td>&#10004;</td><td>integer</td><td>Unique port identifier for the VPCS instance</td></tr>
-    </table>
-
-Sample session
-***************
-
-
-.. literalinclude:: examples/post_vpcsvpcsidnio.txt
-

gns3server/web/documentation.py

@@ -18,6 +18,7 @@
 import re
 import os.path
 
+from gns3server.handlers import *
 from gns3server.web.route import Route
 
 
@@ -33,11 +34,11 @@ class Documentation(object):
             filename = self._file_path(path)
             handler_doc = self._documentation[path]
             with open("docs/api/{}.rst".format(filename), 'w+') as f:
-                f.write('{}\n------------------------------\n\n'.format(path))
+                f.write('{}\n---------------------------------------------\n\n'.format(path))
                 f.write('.. contents::\n')
                 for method in handler_doc["methods"]:
                     f.write('\n{} {}\n'.format(method["method"], path))
-                    f.write('~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n')
+                    f.write('~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n')
                     f.write('{}\n\n'.format(method["description"]))
 
                     if len(method["parameters"]) > 0:
@@ -47,7 +48,7 @@ class Documentation(object):
                             f.write("- **{}**: {}\n".format(parameter, desc))
                         f.write("\n")
 
-                    f.write("Response status codes\n*******************\n")
+                    f.write("Response status codes\n**********************\n")
                     for code in method["status_codes"]:
                         desc = method["status_codes"][code]
                         f.write("- **{}**: {}\n".format(code, desc))
@@ -56,11 +57,11 @@ class Documentation(object):
                     if "properties" in method["input_schema"]:
                         f.write("Input\n*******\n")
                         self._write_definitions(f, method["input_schema"])
-                        self.__write_json_schema(f, method["input_schema"])
+                        self._write_json_schema(f, method["input_schema"])
 
                     if "properties" in method["output_schema"]:
                         f.write("Output\n*******\n")
-                        self.__write_json_schema(f, method["output_schema"])
+                        self._write_json_schema(f, method["output_schema"])
 
                     self._include_query_example(f, method, path)
 
@@ -130,4 +131,5 @@ class Documentation(object):
 
 
 if __name__ == '__main__':
+    print("Generate API documentation")
     Documentation(Route).write()

scripts/documentation.sh

@@ -21,7 +21,9 @@
 
 set -e
 
-py.test
+echo "WARNING: This script should be run at the root directory of the project"
-python3 ../gns3server/web/documentation.py
+
-cd ../docs
+py.test -v
+python3 gns3server/web/documentation.py
+cd docs
 make html