diff --git a/docs/source/_ext/sphinx_marshmallow.py b/docs/source/_ext/sphinx_marshmallow.py new file mode 100644 index 00000000..0eef29e0 --- /dev/null +++ b/docs/source/_ext/sphinx_marshmallow.py @@ -0,0 +1,59 @@ +import importlib +import json +import os +import re +import sys +from typing import Union, List + +from docutils import nodes +from docutils.parsers.rst import Directive + + +class SchemaDirective(Directive): + """ + Support for response/message schemas in the docs. Format: ``.. schema:: rel_path.SchemaClass(arg1=value1, ...)``, + where ``rel_path`` is the path of the schema relative to ``platypush/schemas``. + """ + has_content = True + _schema_regex = re.compile(r'^\s*(.+?)\s*(\((.+?)\))?\s*$') + _schemas_path = os.path.abspath( + os.path.join( + os.path.dirname(os.path.relpath(__file__)), '..', '..', '..', 'platypush', 'schemas')) + + sys.path.insert(0, _schemas_path) + + @staticmethod + def _get_field_value(field) -> str: + metadata = getattr(field, 'metadata', {}) + return metadata.get('example', metadata.get('description', str(field.__class__.__name__).lower())) + + def _parse_schema(self) -> Union[dict, List[dict]]: + m = self._schema_regex.match('\n'.join(self.content)) + schema_module_name = '.'.join(['platypush.schemas', *(m.group(1).split('.')[:-1])]) + schema_module = importlib.import_module(schema_module_name) + schema_class = getattr(schema_module, m.group(1).split('.')[-1]) + schema_args = eval(f'dict({m.group(3)})') + schema = schema_class(**schema_args) + output = { + name: self._get_field_value(field) + for name, field in schema.fields.items() + if not field.load_only + } + + return [output] if schema.many else output + + def run(self): + content = json.dumps(self._parse_schema(), sort_keys=True, indent=2) + block = nodes.literal_block(content, content) + block['language'] = 'json' + return [block] + + +def setup(app): + app.add_directive('schema', SchemaDirective) + + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/docs/source/conf.py b/docs/source/conf.py index 26c32c9e..766c348a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,6 +18,7 @@ import sys # import os # import sys # sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.abspath("./_ext")) # -- Project information ----------------------------------------------------- @@ -50,6 +51,7 @@ extensions = [ 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', 'sphinx_rtd_theme', + 'sphinx_marshmallow', ] # Add any paths that contain templates here, relative to this directory. @@ -134,6 +136,11 @@ html_theme_options = { 'title': 'Firefox Extension', 'internal': False, }, + { + 'href': 'https://f-droid.org/en/packages/tech.platypush.platypush/', + 'title': 'Android App', + 'internal': False, + }, ], } diff --git a/platypush/schemas/__init__.py b/platypush/schemas/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/requirements.txt b/requirements.txt index cc70ede2..40505559 100644 --- a/requirements.txt +++ b/requirements.txt @@ -8,6 +8,9 @@ # YAML configuration support pyyaml +# Responses and schemas +marshmallow + # Support for setting thread/process name # python-prctl diff --git a/setup.py b/setup.py index ab12e0bd..61108333 100755 --- a/setup.py +++ b/setup.py @@ -66,6 +66,7 @@ setup( 'python-dateutil', 'cryptography', 'pyjwt', + 'marshmallow', ], extras_require={