Enhance the documentation (#154)

* Remove api/index.html

* Fix Python API doc & improve JavaScript API doc

* Ignore link to transient file

* more check link fix

* Prettify

Author: fcollonval

.github/workflows/check-release.yml

@@ -12,6 +12,7 @@ jobs:
   check_release:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         group: [check_release, link_check]
         python-version: ["3.9"]
@@ -27,6 +28,8 @@ jobs:
       - name: Check Links
         if: ${{ matrix.group == 'link_check' }}
         uses: jupyter-server/jupyter_releaser/.github/actions/check-links@v1
+        with:
+          ignore_links: "./api/index.html"
       - name: Check Release
         if: ${{ matrix.group == 'check_release' }}
         uses: jupyter-server/jupyter_releaser/.github/actions/check-release@v2

.gitignore

@@ -145,3 +145,5 @@ jupyter_ydoc/_version.py
 !.yarn/releases
 !.yarn/sdks
 !.yarn/versions
+docs/source/api
+docs/source/changelog.md

docs/source/api/index.html

@@ -84,21 +84,14 @@ def setup(app):
 
     # Build JavaScript Docs
     js = HERE.parent.parent / "javascript"
-    js_docs = js / "docs"
     dest_dir = Path(app.outdir) / "api"
 
-    if js_docs.exists():
-        # avoid rebuilding docs because it takes forever
-        # `make clean` to force a rebuild
-        print(f"already have {js_docs!s}")
-    else:
-        print("Building jupyterlab API docs")
-        check_call(["npm", "install"], cwd=str(js))
-        check_call(["npm", "run", "build"], cwd=str(js))
-        check_call(["npm", "run", "docs"], cwd=str(js))
-
-    # Copy JavaScript Docs
-    print(f"Copying {js_docs!s} -> {dest_dir!s}")
+    print("Building @jupyter/ydoc API docs")
+    cmd = ["yarn"] if shutil.which("yarn") is not None else ["npm"]
+    check_call(cmd + ["install"], cwd=str(js))
+    check_call(cmd + ["run", "build"], cwd=str(js))
+    check_call(cmd + ["run", "docs"], cwd=str(js))
+
     if dest_dir.exists():
-        shutil.rmtree(str(dest_dir))
-    shutil.copytree(str(js_docs), str(dest_dir))
+        shutil.rmtree(dest_dir)
+    shutil.copytree(str(js / "docs"), str(dest_dir))

docs/source/changelog.md

@@ -4,6 +4,22 @@
 Python API
 ==========
 
-.. automodule:: jupyter_ydoc.ydoc
+.. automodule:: jupyter_ydoc.ybasedoc
+  :members:
+  :inherited-members:
+
+.. automodule:: jupyter_ydoc.yblob
+  :members:
+  :inherited-members:
+
+.. automodule:: jupyter_ydoc.yfile
+  :members:
+  :inherited-members:
+
+.. automodule:: jupyter_ydoc.ynotebook
+  :members:
+  :inherited-members:
+
+.. automodule:: jupyter_ydoc.yunicode
   :members:
   :inherited-members:

docs/source/conf.py

@@ -24,8 +24,8 @@
     "scripts": {
         "build": "tsc -b",
         "build:test": "tsc --build tsconfig.test.json",
-        "clean": "rimraf lib && rimraf tsconfig.tsbuildinfo",
-        "docs": "typedoc --out ./docs src",
+        "clean": "rimraf lib tsconfig.tsbuildinfo docs",
+        "docs": "typedoc src",
         "eslint": "eslint --ext .js,.jsx,.ts,.tsx --cache --fix .",
         "eslint:check": "eslint --ext .js,.jsx,.ts,.tsx --cache .",
         "lint": "yarn integrity && yarn prettier && yarn eslint",

docs/source/python_api.rst

@@ -1,3 +1,51 @@
 {
-  "out": "../docs/api/shared-models"
+  "externalSymbolLinkMappings": {
+    "@jupyterlab/nbformat": {
+      "CellType": "https://jupyterlab.readthedocs.io/en/latest/api/types/nbformat.CellType.html",
+      "ExecutionCount": "https://jupyterlab.readthedocs.io/en/latest/api/types/nbformat.ExecutionCount.html",
+      "IAttachments": "https://jupyterlab.readthedocs.io/en/latest/api/interfaces/nbformat.IAttachments.html",
+      "IBaseCell": "https://jupyterlab.readthedocs.io/en/latest/api/interfaces/nbformat.IBaseCell.html",
+      "IBaseCellMetadata": "https://jupyterlab.readthedocs.io/en/latest/api/interfaces/nbformat.IBaseCellMetadata.html",
+      "ICodeCell": "https://jupyterlab.readthedocs.io/en/latest/api/interfaces/nbformat.ICodeCell.html",
+      "IMarkdownCell": "https://jupyterlab.readthedocs.io/en/latest/api/interfaces/nbformat.IMarkdownCell.html",
+      "INotebookContent": "https://jupyterlab.readthedocs.io/en/latest/api/interfaces/nbformat.INotebookContent.html",
+      "INotebookMetadata": "https://jupyterlab.readthedocs.io/en/latest/api/interfaces/nbformat.INotebookMetadata.html",
+      "IOutput": "https://jupyterlab.readthedocs.io/en/latest/api/types/nbformat.IOutput.html",
+      "IRawCell": "https://jupyterlab.readthedocs.io/en/latest/api/interfaces/nbformat.IRawCell.html",
+      "IUnrecognizedCell": "https://jupyterlab.readthedocs.io/en/latest/api/interfaces/nbformat.IUnrecognizedCell.html"
+    },
+    "@lumino/coreutils": {
+      "JSONObject": "https://lumino.readthedocs.io/en/latest/api/interfaces/coreutils.JSONObject.html",
+      "JSONValue": "https://lumino.readthedocs.io/en/latest/api/types/coreutils.JSONValue.html",
+      "PartialJSONValue": "https://lumino.readthedocs.io/en/latest/api/types/coreutils.PartialJSONValue.html"
+    },
+    "@lumino/disposable": {
+      "IObservableDisposable": "https://lumino.readthedocs.io/en/latest/api/interfaces/disposable.IObservableDisposable.html"
+    },
+    "@lumino/signaling": {
+      "ISignal": "https://lumino.readthedocs.io/en/latest/api/interfaces/signaling.ISignal.html",
+      "Signal": "https://lumino.readthedocs.io/en/latest/api/classes/signaling.Signal-1.html"
+    },
+    "y-protocols": {
+      "Awareness": "https://docs.yjs.dev/api/about-awareness"
+    },
+    "yjs": {
+      "Array": "https://docs.yjs.dev/api/shared-types/y.array",
+      "Doc": "https://docs.yjs.dev/api/y.doc",
+      "Map": "https://docs.yjs.dev/api/shared-types/y.map",
+      "Text": "https://docs.yjs.dev/api/shared-types/y.text",
+      "UndoManager": "https://docs.yjs.dev/api/undo-manager",
+      "YArrayEvent": "https://docs.yjs.dev/api/shared-types/y.array#y.arrayevent-api",
+      "YEvent": "https://docs.yjs.dev/api/y.event",
+      "YMapEvent": "https://docs.yjs.dev/api/shared-types/y.map#y.mapevent-api",
+      "YTextEvent": "https://docs.yjs.dev/api/shared-types/y.text#y.textevent-api"
+    }
+  },
+  "githubPages": false,
+  "navigationLinks": {
+    "GitHub": "https://github.com/jupyter-server/jupyter_ydoc",
+    "Jupyter": "https://jupyter.org"
+  },
+  "titleLink": "https://jupyter-ydoc.readthedocs.io/en/latest",
+  "out": "./docs"
 }