Initial aproach to generate docs

PythonAPI/docs/client.yml

@@ -0,0 +1,132 @@
+---
+- module_name: client
+  doc: >
+
+  # - CLASSES ------------------------------
+  classes:
+  - class_name: Client
+    doc: >
+      Client used to connect to a Carla server
+
+    # - PROPERTIES -------------------------
+    instance_variables:
+
+    # - METHODS ----------------------------
+    methods:
+    - def_name: __init__
+      params:
+      - param_name: self
+      - param_name: host
+        type: str
+        doc: >
+          IP where Carla is running
+      - param_name: port
+        type: int
+        doc: >
+          Port where Carla is running
+      - param_name: worker_threads
+        type: int
+        default: 0
+        doc: >
+          Number of working threads
+      doc: >
+        Client constructor
+    # --------------------------------------
+    - def_name: set_timeout
+      params:
+      - param_name: self
+      - param_name: seconds
+        type: float
+        doc: >
+          New timeout value in seconds
+      doc: >
+        Sets the server timeout in seconds
+    # --------------------------------------
+    - def_name: get_client_version
+      params:
+      - param_name: self
+      return: str
+      doc: >
+        Get the client version as a string
+    # --------------------------------------
+    - def_name: get_server_version
+      params:
+      - param_name: self
+      return: str
+      doc: >
+        Get the server version as a string
+    # --------------------------------------
+    - def_name: get_world
+      params:
+      - param_name: self
+      doc: >
+        Get the server version as a string
+    # --------------------------------------
+    - def_name: get_available_maps
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: reload_world
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: load_world
+      params:
+      - param_name: self
+      - param_name: map_name
+        type: str
+        doc: >
+          Name of the map to load
+      doc: >
+    # --------------------------------------
+    - def_name: start_recorder
+      params:
+      - param_name: self
+      - param_name: filename
+        type: str
+        doc: >
+          Name of the recorder file to load
+      doc: >
+    # --------------------------------------
+    - def_name: stop_recorder
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: show_recorder_file_info
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: show_recorder_collisions
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: show_recorder_actors_blocked
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: replay_file
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: set_replayer_time_factor
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: apply_batch
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: apply_batch_sync
+      params:
+      - param_name: self
+      doc: >
+...

PythonAPI/docs/doc_gen.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python
+
+# Copyright (c) 2017 Computer Vision Center (CVC) at the Universitat Autonoma de
+# Barcelona (UAB).
+#
+# This work is licensed under the terms of the MIT license.
+# For a copy, see <https://opensource.org/licenses/MIT>.
+
+import os
+import yaml
+
+class MarkdownFile:
+    def __init__(self):
+        self._data = ""
+        self._list_depth = 0
+        self.endl = '  \n'
+
+    def data(self):
+        return str(self._data)
+
+    def push_list(self):
+        self._list_depth = (self._list_depth + 1)
+
+    def pop_list(self):
+        self._list_depth = max(self._list_depth - 1, 0)
+
+    def list_depth(self):
+        if self._list_depth == 0:
+            return ''
+        return ''.join(['  ' * (self._list_depth + 1)])
+
+    def list_item(self, buf):
+        self._data = ''.join([self._data, self.list_depth()[:-2], '* ', buf])
+
+    def numeric_list_item(self, buf):
+        self._data = ''.join([self._data, self.list_depth(), '1. ', buf])
+
+    def text(self, buf):
+        self._data = ''.join([self._data, self.list_depth(), buf])
+
+    def title(self, strongness, buf):
+        self._data = ''.join([
+            self._data, '\n', self.list_depth(), '#' * strongness, ' ', buf, '\n'])
+
+    @classmethod
+    def italic(cls, buf):
+        return ''.join(['_', buf, '_'])
+
+    @classmethod
+    def bold(cls, buf):
+        return ''.join(['**', buf, '**'])
+
+    @classmethod
+    def code(cls, buf):
+        return ''.join(['`', buf, '`'])
+
+    def code_block(self, buf, language=''):
+        return ''.join(['```', language, '\n', self.list_depth(), buf, '\n', self.list_depth(), '```\n'])
+
+
+class YamlIO:
+    """YAML loader and writer"""
+
+    def __init__(self, file_path):
+        """Constructor that loads the yaml file"""
+        with open(file_path) as yaml_file:
+            self.data = yaml.safe_load(yaml_file)
+
+    def gen_markdown(self):
+        """Generates the markdown file"""
+        md_data = ''
+        for module in self.data:
+            # print('Generating module: ' + module['module_name'])
+            md = MarkdownFile()
+            if module['classes']:
+                for c in module['classes']:
+                    class_name = c['class_name']
+                    doc = c['doc']
+                    variables = c['instance_variables']
+                    methods = c['methods']
+
+                    md.title(2, ''.join([md.italic('class'), ' ', md.code('carla.' + class_name)]))
+                    md.text(doc)
+
+                    if variables:
+                        md.title(4, 'Instance Variables')
+                        md.push_list()
+                        for var in variables:
+                            md.list_item(''.join([md.code(var['var_name']), md.endl]))
+                            md.text(var['doc'])
+                        md.pop_list()
+
+                    if methods:
+                        md.title(4, 'Methods')
+                        md.push_list()
+                        for m in methods:
+                            param = ''
+                            for p in m['params']:
+                                p_type = ''.join([': ', str(p['type'])]) if 'type' in p else ''
+                                default = ''.join([' = ', str(p['default'])]) if 'default' in p else ''
+                                param = ''.join([param, p['param_name'], p_type, default, ', '])
+                            param = param[:-2] # delete the last ', '
+                            return_type = ''.join([' -> ', m['return']]) if 'return' in m else ''
+                            md.list_item(''.join([md.code(''.join([m['def_name'], '(', param, ')', return_type])), md.endl]))
+                            if 'doc' in m and m['doc'] is not '':
+                                doc = m['doc'].strip()
+                                md.text(''.join([doc, md.endl]))
+                        md.pop_list()
+            md_data = ''.join([md_data, md.data().strip()])
+        return md_data
+
+
+def main():
+    """Main function"""
+    script_path = os.path.dirname(os.path.abspath(__file__))
+    yml_files = [f for f in os.listdir(script_path) if f.endswith('.yml')]
+
+    data = ''
+
+    for yml_file in yml_files:
+        yml = YamlIO(os.path.join(script_path, yml_file))
+        data = '\n\n'.join([data, yml.gen_markdown()])
+    data = data.strip()
+    with open(os.path.join(script_path, 'Output.md'), 'w') as md_file:
+        md_file.write(data)
+
+if __name__ == "__main__":
+    main()

PythonAPI/docs/map.yml

@@ -0,0 +1,56 @@
+---
+- module_name: map
+  doc: >
+
+  # - CLASSES ------------------------------
+  classes:
+  - class_name: Map
+    doc: >
+      Map description that provides a waypoint query system
+
+    # - PROPERTIES -------------------------
+    instance_variables:
+    - var_name: name
+      doc: >
+        Map name
+
+    # - METHODS ----------------------------
+    methods:
+    - def_name: get_spawn_points
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: get_waypoint
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: get_topology
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: generate_waypoints
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: transform_to_geolocation
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: to_opendrive
+      params:
+      - param_name: self
+      doc: >
+    # --------------------------------------
+    - def_name: save_to_disk
+      params:
+      - param_name: self
+      - param_name: path
+        doc: >
+          Path where will be saved
+      doc: >
+        Save the OpenDrive of the current map to disk