Deprecate CWLGen

README.md

@@ -1,4 +1,45 @@
-# python-cwlgen
+# python-cwlgen (deprecated)
+
+## Deprecated
+
+`python-cwlgen` is now deprecated, please use [`cwl-utils >= 0.4`](https://github.com/common-workflow-language/cwl-utils).
+
+```sh
+from cwl_utils import parser_v1_0
+
+# You could alias this as cwlgen to simplify the migration
+from cwl_utils import parser_v1_0 as cwlgen
+```
+
+Migration notes:
+
+- Method changes
+  - `get_dict() → save()` 
+  - `parse_cwl(cwlfile)` → `load_document(cwlfile)`
+  - `parse_dict` → No super clear analogue, but loaded through `_RecordLoader(CommandLineTool)` || `_UnionLoader((CommandLineToolLoader, ...workflow + other loaders)`
+
+- Field names:
+  - Uses `camelCase` instead of `snake_case`
+  - No more special field names, eg:
+    - `tool_id` | `workflow_id` | `input_id` | etc → `id`
+    - `StepInput`: `inputs` → `in_`
+
+- Other notes:
+  - Classes aren't nested anymore, ie: `cwlgen.InitialWorkDirRequirement.Dirent` → `cwl_utils.parser_v1_0.Dirent`.
+  - Take care if you're migrating to a newer spec, as some classes might have changed names (notably: `InputParameter` -> `WorkflowInputParameter`)
+  - Don't forget to catch all references of cwlgen, as missing one (or using mismatch versions of the parser) will cause:
+
+    ```python
+    raise RepresenterError('cannot represent an object: %s' % (data,))
+    ruamel.yaml.representer.RepresenterError: cannot represent an object: 
+    <cwlgen.common.CommandInputArraySchema object at 0x1100a5780>
+    ```
+
+If you have issues with the migration, please see [this thread](https://github.com/common-workflow-language/python-cwlgen/issues/27) or raise an issue on CWLUtils.
+
+---
+
+## Original README
 
 [![Build Status](https://travis-ci.org/common-workflow-language/python-cwlgen.svg?branch=master)](https://travis-ci.org/common-workflow-language/python-cwlgen)
 [![codecov](https://codecov.io/gh/common-workflow-language/python-cwlgen/branch/master/graph/badge.svg)](https://codecov.io/gh/common-workflow-language/python-cwlgen)
@@ -12,7 +53,7 @@ The library works for both Python 2.7.12+ and 3.6.0.
 ------------------------
 
 
-# Common Workflow Language
+## Common Workflow Language
 
 [Common Workflow Language (CWL)](https://www.commonwl.org/v1.0/index.html) is a language to describe workflows. 
 The [user guide](http://www.commonwl.org/user_guide/01-introduction/index.html)

cwlgen/__init__.py

@@ -2,6 +2,16 @@
 Library to handle the manipulation and generation of CWL tool
 '''
 
+import warnings
+
+warnings.warn(
+    "The cwlgen module is deprecated, please use "
+    "cwl-utils >= 0.4: https://github.com/common-workflow-language/cwl-utils",
+    DeprecationWarning,
+    stacklevel=2
+)
+
+
 #  Import  ------------------------------
 
 # General libraries

doc/source/classes.rst

@@ -26,10 +26,10 @@ This is the (abstract) base requirement class.
     :special-members:
     :exclude-members: __weakref__
 
-InlineJavascriptReq
-"""""""""""""""""""
+InlineJavascriptRequirement
+"""""""""""""""""""""""""""
 
-.. autoclass:: cwlgen.InlineJavascriptReq
+.. autoclass:: cwlgen.InlineJavascriptRequirement
     :members:
     :private-members:
     :special-members:

doc/source/index.rst

@@ -1,9 +1,54 @@
 .. python-cwlgen - Python library for manipulation and generation of CWL tools.
 
 
-Welcome to python-cwlgen's documentation!
+Python-CWLGen (**Deprecated**)
 =========================================
 
+.. warning::
+
+   ``python-cwlgen`` is now deprecated, please use `cwl-utils >= 0.4 <https://github.com/common-workflow-language/cwl-utils>`_.
+
+Example migration:
+
+.. code-block:: bash
+
+   from cwl_utils import parser_v1_0
+
+   # You could alias this as cwlgen to simplify the migration
+   from cwl_utils import parser_v1_0 as cwlgen
+
+
+Migration notes:
++++++++++++++++++++++
+
+- Method changes
+
+  - ``get_dict() → save()`` 
+  - ``parse_cwl(cwlfile)`` → ``load_document(cwlfile)``
+  - ``parse_dict`` → No super clear analogue, but loaded through ``_RecordLoader(CommandLineTool)`` || ``_UnionLoader((CommandLineToolLoader, ...workflow + other loaders)``
+
+- Field names:
+
+  - Uses ``camelCase`` instead of ``snake_case``
+  - No more special field names, eg:
+    - ``tool_id`` | ``workflow_id`` | ``input_id`` | etc → ``id``
+    - ``StepInput``: ``inputs`` → ``in_``
+
+- Other notes:
+
+  - Classes aren't nested anymore, ie: ``cwlgen.InitialWorkDirRequirement.Dirent`` → ``cwlutils``.
+  - Take care if you're migrating to a newer spec, as some classes might have changed names (notably: ``InputParameter`` -> ``WorkflowInputParameter``)
+  - Don't forget to catch all references of cwlgen, as missing one (or using mismatch versions of the parser) will cause:
+
+    .. code-block:: python
+
+       raise RepresenterError('cannot represent an object: %s' % (data,))
+       ruamel.yaml.representer.RepresenterError: cannot represent an object:
+       <cwlgen.common.CommandInputArraySchema object at 0x1100a5780>
+
+If you have issues with the migration, please see `this thread <https://github.com/common-workflow-language/python-cwlgen/issues/27>`_ or raise an issue on CWLUtils.
+
+
 .. image:: https://travis-ci.org/common-workflow-language/python-cwlgen.svg?branch=master&style=flat
     :target: https://travis-ci.org/common-workflow-language/python-cwlgen
     :alt: Travis Build Status