New docs generation (terminusdb#405)

* Fix docs and license

* Try to insert docs

* Use poetry

* Add commit message and author

* Remove the commit message and author

* Fix integration tests because of new requests lib (terminusdb#395)

* Fix conversion of sys:JSON type schema to Python (terminusdb#400)

If a class contained a "sys:JSON" property, it wouldn't
convert to a normal Python class as it should.

Fixes issue terminusdb#397

* Add version 10.2.3

* Change title of application and description

* Get examples

* ci: don't do poetry interactively

* Fix parameters for patch function

* Only generate docs on version push or manual run

Author: rrooij

.github/insert_docs.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+import inspect
+import json
+
+import terminusdb_client
+from numpydoc.docscrape import FunctionDoc, ClassDoc
+
+def parameter_to_document(param):
+    return {'@type': 'Parameter', 'type': param.type, 'name': param.name, 'summary': "\n".join(param.desc)}
+
+classes_to_scan = ['Client']#, 'WOQLQuery']
+classes = []
+
+for name, obj in inspect.getmembers(terminusdb_client):
+    if inspect.isclass(obj) and 'terminusdb' in str(obj):
+        if name in classes_to_scan:
+            docstring_class = ClassDoc(obj)
+            class_params = [parameter_to_document(x) for x in docstring_class['Attributes']]
+            functions = []
+            for func in obj.__dict__.values():
+                if callable(func) and func.__doc__:
+                    docstring_function = FunctionDoc(func)
+                    parameters = [parameter_to_document(x) for x in docstring_function['Parameters']]
+                    examples = '\n'.join(docstring_function['Examples'])
+                    if len(docstring_function['Returns']) > 0:
+                        ret = docstring_function['Returns'][0] # Functions always have one return
+                        returns = {'@type': 'Returns', 'name': '', 'type': ret.type}
+                        if len(ret.desc) > 0:
+                            returns['summary'] = "\n".join(ret.desc)
+                    else:
+                        returns = {'@type': 'Returns', 'name': '', 'type': 'void'}
+                    function_obj = {'@type': 'Definition',
+                                    'name': func.__name__,
+                                    'parameters': parameters,
+                                    'returns': returns,
+                                    'examples': [examples] if examples != "" else None,
+                                    'summary': "\n".join(docstring_function['Summary'])}
+                    functions.append(function_obj)
+            class_obj = {'@type': 'Class', 'name': name, 'summary': "\n".join(docstring_class['Summary']), 'memberVariables': class_params, 'memberFunctions': functions}
+            classes.append(class_obj)
+
+application = {
+    '@type': 'Application',
+    'version': terminusdb_client.__version__.__version__,
+    'name': terminusdb_client.__version__.__title__,
+    'summary': terminusdb_client.__version__.__description__,
+    'language': 'Python',
+    'license': terminusdb_client.__version__.__license__,
+    'modules': [
+        {
+            '@type': 'Module',
+            'name': 'terminusdb_client',
+            'classes': classes
+         }
+    ]}
+
+print(json.dumps(application))

.github/workflows/docs.yml

@@ -7,6 +7,7 @@ on:
   push:
     tags:
       - v*
+  workflow_dispatch:
 
 jobs:
   make_docs:
@@ -18,29 +19,15 @@ jobs:
       uses: actions/setup-python@v4
       with:
         python-version: '3.x'
-    - name: Generate docs
+    - name: Install requirements
       run: |
-        git clone --single-branch --branch add_gitbook https://github.com/terminusdb/pydoc-markdown.git
-        python -m pip install --upgrade pip
-        pip install ./pydoc-markdown
-        pydoc-markdown
-        cd docs
-        python -m pip install -r requirements.txt
-        make markdown
-        python generateGitbookMD.py
-        cp -r reference/* build/markdown/gitbook-md/
-    - name: Set destination BRANCH_NAME for docs repo
-      run: echo "BRANCH_NAME=Python-Reference-Updates-$(date +%s)" >> $GITHUB_ENV
-    - name: Create pull request in terminusdb/terminusdb-docs
-      uses: paygoc6/[email protected]
-      env:
-        API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}
-      with:
-        source_folder: 'docs/build/markdown/gitbook-md'
-        destination_repo: 'terminusdb/terminusdb-docs'
-        destination_folder: 'guides/reference-guides/python-client-reference'
-        destination_base_branch: 'main'
-        destination_head_branch: ${{ env.BRANCH_NAME }}
-        user_email: '[email protected]'
-        user_name: 'rrooij'
-        pull_request_reviewers: 'GavinMendelGleason'
+        pip install poetry
+        poetry install -n
+    - name: Generate docs JSON
+      run: poetry run python .github/insert_docs.py > docs.json
+    - name: Upload to TerminusCMS
+      run: |
+        curl -H 'Authorization: Token ${{ secrets.TERMINUSCMS_TOKEN}}' \
+             -H 'Content-Type: application/json' \
+            '${{ secrets.TERMINUSCMS_URL}}' -d @./docs.json
+

terminusdb_client/__version__.py

@@ -1,9 +1,9 @@
-__title__ = "woqlClient"
-__description__ = "woqlClient library for accessing the Terminus DB API"
+__title__ = "terminusdb-client"
+__description__ = "TerminusDB client library for accessing the Terminus DB API"
 __url__ = ""
 __version__ = "10.2.3"
 __build__ = 00
 __author__ = "TerminusDB group"
 __author_email__ = "[email protected]"
-__license__ = "GNU General Public License v3 (GPLv3)"
+__license__ = "Apache 2.0"
 __copyright__ = "Copyright 2019 datachemist"