Migrate some docstrings to ReST

Author: u8sand

appyter/ext/pathlib/assertions.py

@@ -1,15 +1,15 @@
-''' ```eval_rst
+'''
 This module contains :class:`appyter.fields.Field`, the base class for all fields
 defined in :mod:`appyter.profiles.default.fields`.
-``` '''
+'''
 
 from markupsafe import Markup
 from appyter.ext.flask import request_get
 
 class PartialField:
   ''' Partial instantiation of a field
   Replaces a decorator so that we can still identify it as
-   a callable which will produce a field.
+  a callable which will produce a field.
   '''
   def __init__(self, field, **kwargs):
     self._field = field
@@ -47,10 +47,9 @@ def as_dict(self):
 
 class Field(dict):
   ''' Base field for which all fields derive
-  ```eval_rst
   Base class for all Field objects representing a value that will later be provided via a front-end form.
   See :mod:`appyter.profiles.default.fields` for the actual fields.
-  ``` '''
+  '''
   def __init__(self,
       name=None,
       label=None,
@@ -62,7 +61,7 @@ def __init__(self,
       section=None,
       _env=None,
       **kwargs):
-    '''
+    r'''
     :param name: (str) A name that will be used to refer to the object as a variable and in the HTML form.
     :param label: (str) A human readable label for the field for the HTML form
     :param description: (Optional[str]) A long human readable description for the field for the HTML form
@@ -71,7 +70,7 @@ def __init__(self,
     :param default: (Any) A default value as an example and for use during prototyping
     :param section: (Optional[str]) The name of a SectionField for which to nest this field under, defaults to a root SectionField
     :param value: (INTERNAL Any) The raw value of the field (from the form for instance)
-    :param **kwargs: Additional keyword arguments used by other fields
+    :param \**kwargs: Additional keyword arguments used by other fields
     '''
     super().__init__(
       field=self.field,
@@ -113,7 +112,7 @@ def constraint(self):
     return (self.raw_value is None and not self.args.get('required')) or (self.raw_value in self.choices)
 
   def render(self, **kwargs):
-    ''' Return a rendered version of the field (form)
+    r''' Return a rendered version of the field (form)
 
     :param \**kwargs: The instance values of the form e.g. `Field.render(**field.args)`
     '''

appyter/fields.py

@@ -1,4 +1,5 @@
-''' IPython magic for making templating easy~. This basically
+r'''
+IPython magic for making templating easy~. This basically
 just allows our jinja-type language to be executed in place
 injecting the defaults into the environment so we can easily
 debug the notebook at the same time as building the appyter.
@@ -10,25 +11,24 @@
 
 Usage (put the following in the first cell):
 
-```python
-#%%appyter init
-from appyter import magic
-magic.init(lambda _=globals: _())
-```
+.. code-block:: python
+
+  #%%appyter init
+  from appyter import magic
+  magic.init(lambda _=globals: _())
 '''
 
 '''
 Setup given globals
 '''
 def init(_globals, verbose=False, ipynb='app.ipynb', mode='magic', safe_mode=False, **kwargs):
-  ''' Initialize appyter magic.
+  r''' Initialize appyter magic.
 
   Sets up a jinj2 environment and injects %%appyter magic into your environment.
   
-  :param _globals: (Dict[str, Any]) A callable with your globals for the purpose of injection, basically just: `lambda _=globals: _()`
+  :param _globals: (Dict[str, Any]) A callable with your globals for the purpose of injection, basically just: ``lambda _=globals: _()``
   :param verbose: (Optional[bool]) Expand exception reporting to be more verbose
   '''
-  import os
   import jinja2
   import jinja2.meta
   import traceback
@@ -37,23 +37,29 @@ def init(_globals, verbose=False, ipynb='app.ipynb', mode='magic', safe_mode=Fal
   from IPython.core.magic import register_cell_magic
   from IPython.display import display, Markdown, HTML
 
-  '''
+  r'''
   register_cell_magic allows function to execute an entire cell with the following call structure:
-  ```python
-  %%my_magic whatever
-  all
-  my
-  data
-  ```
-  Results in a call:
-  ```python
-  my_magic(
-    "whatever",
-    """all
+
+  .. code-block:: python
+
+    %%my_magic whatever
+    all
     my
-    data"""
-  )
-  ```
+    data
+
+  Results in a call:
+
+  .. code-block:: python
+
+    my_magic(
+      "whatever",
+      """
+      all
+      my
+      data
+      """
+    )
+
   '''
 
   @register_cell_magic

appyter/magic.py

@@ -1,6 +1,6 @@
-''' ```eval_rst
+'''
 Each submodule represents a profile extending from :mod:`appyter.profiles.default` which provide different rendering themes.
-``` '''
+'''
 
 import os
 from appyter.cli import cli

appyter/profiles/__init__.py

@@ -1,5 +1,3 @@
 ''' Bare profile with no styling.
-```eval_rst
 The default profile contains the :mod:`appyter.profiles.default.fields`, :mod:`appyter.profiles.default.filters`, and :mod:`appyter.profiles.default.templates` usable by all other profiles.
-```
 '''

appyter/profiles/default/__init__.py

@@ -3,7 +3,7 @@
 from appyter.ext.re import re_full
 
 class AutocompleteField(Field):
-  ''' Representing a field that accepts a string with autocomplete.
+  r''' Representing a field that accepts a string with autocomplete.
   Auto complete will use `choices` or alternatively `file_path` -- a url to load the choices as an array.
 
   Be careful with this field, consider defining a constraint regex. Note that it is equivalent to
@@ -21,7 +21,7 @@ class AutocompleteField(Field):
   :param examples: (Optional[Union[List[str], Dict[str, str]]]) Named strings to provide as clickable examples
   :param section: (Optional[str]) The name of a SectionField for which to nest this field under, defaults to a root SectionField
   :param value: (INTERNAL Any) The raw value of the field (from the form for instance)
-  :param **kwargs: Additional keyword arguments used by other fields
+  :param \**kwargs: Additional keyword arguments used by other fields
   '''
   def __init__(self, constraint=r'.*', hint=None, **kwargs):
     super().__init__(

appyter/profiles/default/fields/AutocompleteField.py

@@ -1,7 +1,7 @@
 from appyter.fields import Field
 
 class BoolField(Field):
-  ''' Represing a true or false value with a checkbox.
+  r''' Represing a true or false value with a checkbox.
 
   :param name: (str) A name that will be used to refer to the object as a variable and in the HTML form.
   :param label: (str) A human readable label for the field for the HTML form
@@ -12,7 +12,7 @@ class BoolField(Field):
   :param yes_label: (Optional[str]) The text instead of "Yes"
   :param no_label: (Optional[str]) The text instead of "No"
   :param value: (INTERNAL Any) The raw value of the field (from the form for instance)
-  :param **kwargs: Additional keyword arguments used by other fields
+  :param \**kwargs: Additional keyword arguments used by other fields
   '''
   def __init__(self, **kwargs):
     super().__init__(**kwargs)

appyter/profiles/default/fields/BoolField.py

@@ -1,7 +1,7 @@
 from appyter.fields import Field
 
 class ChoiceField(Field):
-  ''' Represing a choice of string values with a combo box.
+  r''' Represing a choice of string values with a combo box.
 
   :param name: (str) A name that will be used to refer to the object as a variable and in the HTML form.
   :param label: (str) A human readable label for the field for the HTML form
@@ -11,7 +11,7 @@ class ChoiceField(Field):
   :param default: (str) A default value as an example and for use during prototyping
   :param section: (Optional[str]) The name of a SectionField for which to nest this field under, defaults to a root SectionField
   :param value: (INTERNAL Any) The raw value of the field (from the form for instance)
-  :param **kwargs: Additional keyword arguments used by other fields
+  :param \**kwargs: Additional keyword arguments used by other fields
   '''
   def __init__(self, **kwargs):
     super().__init__(**kwargs)

appyter/profiles/default/fields/ChoiceField.py

@@ -1,20 +1,20 @@
 from appyter.fields import Field
 
 class DescriptionField(Field):
-  ''' Representing text between fields
+  r'''
+  Representing text between fields
 
-  Usage:
-  ```python
-  {% do DescriptionField(
-    name='my_fieldname',
-    text='My Description',
-  ) %}
-  ```
+  .. code-block:: python
+
+    {% do DescriptionField(
+      name='my_fieldname',
+      text='My Description',
+    ) %}
 
   :param name: (str) A name that will be used to refer to the object as a variable and in the HTML form.
   :param text: (str) A human readable, HTML parsable text
   :param section: (Optional[str]) The name of a SectionField for which to nest this field under, defaults to a root SectionField
-  :param **kwargs: Additional keyword arguments used by other fields
+  :param \**kwargs: Additional keyword arguments used by other fields
   '''
   def __init__(self, **kwargs):
     super().__init__(**kwargs)

appyter/profiles/default/fields/DescriptionField.py

@@ -6,13 +6,15 @@
 from appyter.ext.re import re_full
 
 class FileField(Field):
-  ''' Representing a File URL.
+  r'''
+  Representing a File URL.
 
   The field ends up being a string of the file path, which will be relative to the appyter notebook.
-  ```python
-  import pandas as pd
-  df = pd.read_csv({{ FileField(name='my-csv', label='My CSV') }})
-  ```
+
+  .. code-block:: python
+
+    import pandas as pd
+    df = pd.read_csv({{ FileField(name='my-csv', label='My CSV') }})
 
   Importantly, a FileField ultimately resolves to a URL supporting several schemes. Appyters ensure
    that url is available as an actual file when the appyter executes.
@@ -28,7 +30,7 @@ class FileField(Field):
     paths can be relative i.e. `{ "my_file.txt": url_for('static', filename='my_file.txt') }`, or a remote url.
   :param section: (Optional[str]) The name of a SectionField for which to nest this field under, defaults to a root SectionField
   :param value: (INTERNAL Any) The raw value of the field (from the form for instance)
-  :param **kwargs: Remaining arguments passed down to :class:`appyter.fields.Field`'s constructor.
+  :param \**kwargs: Remaining arguments passed down to :class:`appyter.fields.Field`'s constructor.
   '''
   def __init__(self, default=None, constraint=r'.*', **kwargs):
     super().__init__(