Merge pull request #241 from blink1073/static-examples

Add static examples in docs
jupyterlab · Sep 30, 2021 · 57fd0e4 · 57fd0e4
2 parents d6c5e4b + 51cdc81
commit 57fd0e4
Show file tree

Hide file tree

Showing 27 changed files with 95 additions and 38 deletions.
diff --git a/.github/jupyterlab-probot.yml b/.github/jupyterlab-probot.yml
diff --git a/.gitignore b/.gitignore
@@ -13,7 +13,10 @@ review/api/temp
 docs/source/changelog.md
 
 # generated api files
-docs/api
+docs/source/api
+
+# generated example files
+docs/source/examples
 
 # jetbrains ide stuff
 *.iml

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -45,3 +45,14 @@ There are also tests in some of the examples. These can be run as:
 ```bash
 yarn test:examples
 ```
+
+## Static Examples
+
+There are static examples built into the documentation.  Having them in docs allows us to test examples
+in the ReadTheDocs build for a PR.
+
+To add an example to the static examples:
+
+- Add appropriate link in: `docs/source/examples.rst`
+- Add the example name to the `EXAMPLES` in `docs/source/conf.py`
+- Add `ignore-links` config in `package.json`
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -30,6 +30,7 @@
 
 
 HERE = osp.abspath(osp.dirname(__file__))
+EXAMPLES = ["accordionpanel", "datagrid", "dockpanel"]
 
 # -- General configuration ------------------------------------------------
 
@@ -102,8 +103,8 @@ def build_api_docs(out_dir):
     """build js api docs"""
     docs = osp.join(HERE, os.pardir)
     root = osp.join(docs, os.pardir)
-    docs_api = osp.join(docs, "api")
-    api_index = osp.join(docs_api, "index.html")
+    docs_api = osp.join(docs, "source", "api")
+    api_index = osp.join(docs_api, "algorithm", "index.html")
 
     if osp.exists(api_index):
         # avoid rebuilding docs because it takes forever
@@ -122,10 +123,43 @@ def build_api_docs(out_dir):
     if osp.exists(dest_dir):
         shutil.rmtree(dest_dir)
     shutil.copytree(docs_api, dest_dir)
+    shutil.copy(osp.join(HERE, 'api_index.html'), osp.join(dest_dir, 'index.html'))
 
-    dest = osp.join(dest_dir, 'index.html')
-    shutil.copy(osp.join(HERE, 'api_index.html'), dest)
+# build js examples and stage them to the build directory
+def build_examples(out_dir):
+    """build js example docs"""
+    docs = osp.join(HERE, os.pardir)
+    root = osp.join(docs, os.pardir)
+    examples_dir = osp.join(docs, "source", "examples")
+    example_index = osp.join(examples_dir, EXAMPLES[0], "index.html")
 
+    if osp.exists(example_index):
+        # avoid rebuilding examples because it takes forever
+        # `make clean` to force a rebuild
+        print(f"already have examples")
+    else:
+        print("Building lumino examples")
+        npm = [shutil.which('npm')]
+        check_call(npm + ['install', '-g', 'yarn'], cwd=root)
+        yarn = [shutil.which('yarn')]
+        check_call(yarn, cwd=root)
+        check_call(yarn + ["build"], cwd=root)
+        check_call(yarn + ["build:examples"], cwd=root)
+
+        # Copy the examples into source so the JS files get picked up
+        for example in EXAMPLES:
+            source = osp.join(root, "examples", f"example-{example}")
+            dest_dir = osp.join(docs, "source", "examples", example)
+            print(f"Copying {source} -> {dest_dir}")
+            if osp.exists(dest_dir):
+                shutil.rmtree(dest_dir)
+            shutil.copytree(source, dest_dir)
+
+    dest_dir = osp.join(out_dir, "examples")
+    print(f"Copying {examples_dir} -> {dest_dir}")
+    if osp.exists(dest_dir):
+        shutil.rmtree(dest_dir)
+    shutil.copytree(examples_dir, dest_dir)
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -205,7 +239,6 @@ def build_api_docs(out_dir):
      'Project Jupyter', 'manual'),
 ]
 
-
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
@@ -215,7 +248,6 @@ def build_api_docs(out_dir):
      [author], 1)
 ]
 
-
 # -- Options for Texinfo output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
@@ -227,8 +259,6 @@ def build_api_docs(out_dir):
      'Miscellaneous'),
 ]
 
-
-
 # -- Options for Epub output ----------------------------------------------
 
 # Bibliographic Dublin Core info.
@@ -249,8 +279,6 @@ def build_api_docs(out_dir):
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ['search.html']
 
-
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
 
@@ -260,3 +288,4 @@ def setup(app):
     shutil.copy(osp.join(HERE, '..', '..', 'CHANGELOG.md'), dest)
     app.add_css_file('css/custom.css')  # may also be an URL
     build_api_docs(app.outdir)
+    build_examples(app.outdir)
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -0,0 +1,12 @@
+
+
+Examples
+========
+
+Rendered static examples
+
+`Accordion Panel <examples/accordionpanel/index.html>`_
+
+`DataGrid <examples/datagrid/index.html>`_
+
+`DockPanel <examples/dockpanel/index.html>`_
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -3,15 +3,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Lumino's documentation!
-==================================
+Lumino
+======
 
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
    changelog
    api
+   examples
 
 Indices and tables
 ==================

diff --git a/examples/example-accordionpanel/index.html b/examples/example-accordionpanel/index.html
@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <link href="http://maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet">
+  <link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet">
   <script type="text/javascript" src="build/bundle.example.js"></script>
 </head>
 <body>

diff --git a/examples/example-dockpanel/index.html b/examples/example-dockpanel/index.html
@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <link href="http://maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet">
+  <link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet">
   <script type="text/javascript" src="build/bundle.example.js"></script>
 </head>
 <body>

diff --git a/package.json b/package.json
@@ -18,7 +18,7 @@
     "clean:examples": "lerna run clean --scope \"@lumino/example-*\"",
     "clean:src": "lerna run clean --scope \"@lumino/!(test-|example-)*\"",
     "clean:tests": "lerna run clean:tests",
-    "docs": "rimraf docs/api && lerna run build:src --concurrency 1 && lerna run docs",
+    "docs": "rimraf docs/source/api && lerna run build:src --concurrency 1 && lerna run docs",
     "eslint": "eslint --ext .js,.jsx,.ts,.tsx --cache --fix .",
     "eslint:check": "eslint --ext .js,.jsx,.ts,.tsx --cache .",
     "get:dependency": "get-dependency",
@@ -58,7 +58,10 @@
     ],
     "options": {
       "ignore-links": [
-        "./api/index.html"
+        "./api/index.html",
+        "examples/accordionpanel/index.html",
+        "examples/datagrid/index.html",
+        "examples/dockpanel/index.html"
       ]
     },
     "hooks": {

diff --git a/packages/algorithm/tdoptions.json b/packages/algorithm/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/algorithm",
+  "out": "../../docs/source/api/algorithm",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/application/tdoptions.json b/packages/application/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/application",
+  "out": "../../docs/source/api/application",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["../packages/*"]

diff --git a/packages/collections/tdoptions.json b/packages/collections/tdoptions.json
@@ -3,7 +3,7 @@
   "mode": "file",
   "target": "es5",
   "module": "es5",
-  "out": "../../docs/api/collections",
+  "out": "../../docs/source/api/collections",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/commands/tdoptions.json b/packages/commands/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/commands",
+  "out": "../../docs/source/api/commands",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/coreutils/tdoptions.json b/packages/coreutils/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/coreutils",
+  "out": "../../docs/source/api/coreutils",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/datagrid/tdoptions.json b/packages/datagrid/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/datagrid",
+  "out": "../../docs/source/api/datagrid",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/datastore/tdoptions.json b/packages/datastore/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/datastore",
+  "out": "../../docs/source/api/datastore",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/disposable/tdoptions.json b/packages/disposable/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/disposable",
+  "out": "../../docs/source/api/disposable",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/domutils/tdoptions.json b/packages/domutils/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/domutils",
+  "out": "../../docs/source/api/domutils",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/dragdrop/tdoptions.json b/packages/dragdrop/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/dragdrop",
+  "out": "../../docs/source/api/dragdrop",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/keyboard/tdoptions.json b/packages/keyboard/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/keyboard",
+  "out": "../../docs/source/api/keyboard",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/messaging/tdoptions.json b/packages/messaging/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/messaging",
+  "out": "../../docs/source/api/messaging",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/polling/tdoptions.json b/packages/polling/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/polling",
+  "out": "../../docs/source/api/polling",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/properties/tdoptions.json b/packages/properties/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/properties",
+  "out": "../../docs/source/api/properties",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/signaling/tdoptions.json b/packages/signaling/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/signaling",
+  "out": "../../docs/source/api/signaling",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/virtualdom/tdoptions.json b/packages/virtualdom/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/virtualdom",
+  "out": "../../docs/source/api/virtualdom",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/packages/widgets/tdoptions.json b/packages/widgets/tdoptions.json
@@ -9,7 +9,7 @@
     "lib.es2015.promise.d.ts",
     "lib.dom.d.ts"
   ],
-  "out": "../../docs/api/widgets",
+  "out": "../../docs/source/api/widgets",
   "baseUrl": ".",
   "paths": {
     "@lumino/*": ["node_modules/@lumino/*"]

diff --git a/typedoc.js b/typedoc.js
@@ -21,8 +21,8 @@ module.exports = {
   entryPoints,
   exclude,
   name: '@lumino',
-  out: 'docs/api',
-  // json: 'docs/api.json',
+  out: 'docs/source/api',
+  // json: 'docs/source/api.json',
   readme: 'README.md',
   theme: 'typedoc-theme',
   tsconfig: 'tsconfigdoc.json'