Merge pull request #6656 from jaipreet-s/devdocs

Update the extension tutorial to follow APOD

RELEASE.md

@@ -126,7 +126,7 @@ the next release:
 - Clone the repo if you don't have it
 
 ```bash
-git clone git@github.com:jupyterlab/jupyterlab_xkcd.git
+git clone git@github.com:jupyterlab/jupyterlab_apod.git
 ```
 
 #### Simple updates by rebasing
@@ -157,8 +157,8 @@ git rm -rf .
 git clean -dfx
 cookiecutter path-to-local-extension-cookiecutter-ts
 # Fill in the values from the previous branch package.json initial commit
-cp -r jupyterlab_xkcd/ .
-rm -rf jupyterlab_xkcd
+cp -r jupyterlab_apod/ .
+rm -rf jupyterlab_apod
 ```
 
 - Create a new PR in JupyterLab.
@@ -168,14 +168,14 @@ rm -rf jupyterlab_xkcd
   file from the previous branch, as well as the `package.json` fields up to
   `license`. Bump the version number in preparation for publishing to npm.
 
-#### Publishing xkcd tutorial changes
+#### Publishing extension tutorial changes
 
 - Replace the tag references in the tutorial with the new branch number, e.g.
-  replace `0.28-` with `0.29-`. Prefix the new tags with the branch name, e.g.
-  `0.28-01-show-a-panel`
+  replace `1.0-` with `1.1-`. Prefix the new tags with the branch name, e.g.
+  `1.0-01-show-a-panel`
   ```bash
   git tag 0.XX-01-show-a-panel HEAD~5
-  git tag 0.XX-02-show-a-comic HEAD~4
+  git tag 0.XX-02-show-an-image HEAD~4
   git tag 0.XX-03-style-and-attribute HEAD~3
   git tag 0.XX-04-refactor-and-refresh HEAD~2
   git tag 0.XX-05-restore-panel-state HEAD~1
@@ -185,9 +185,9 @@ rm -rf jupyterlab_xkcd
   ```bash
   git push origin 0.XX --tags
   ```
-  Set the branch as the default branch (see `github.com/jupyterlab/jupyterlab_xkcd/settings/branches`).
+  Set the branch as the default branch (see `github.com/jupyterlab/jupyterlab_apod/settings/branches`).
 - If there were changes to the example in the documentation, submit a PR to JupyterLab
-- Publish the new `@jupyterlab/xkcd` npm package. Make sure to update the version
+- Publish the new `@jupyterlab/apod` npm package. Make sure to update the version
   number in the last commit of the branch.
   ```bash
   npm publish

docs/source/developer/documentation.rst

@@ -108,27 +108,34 @@ Our documentation should contain screenshots and animations that
 illustrate and demonstrate the software. Here are some guidelines for
 preparing them:
 
--  Set screen resolution to non-hidpi (non-retina)
-
--  Set browser viewport to 1280x720 px.
-   The Firefox Web Developer extension and Chrome Developer Tools offer
-   device specific rendering that enables you to set this viewport resolution.
-
--  Capture the viewport, **not the full browser window**,
-   using the capture software of your choice. **Do not include any of the
-   desktop background**.
-
--  For PNGs, reduce their size using pngquant.
-   For movies, upload them to the IPython/Juptyter YouTube channel
-   and embed them in the docs with an iframe. The pngs can live in the main repository.
-   The movies should be added to the ``jupyterlab-media`` repository.
-
--  Use `www.youtube-nocookie.com` website, which can be found by
-   clicking on the 'privacy-enhanced' embedding option in the Share dialog on YouTube.
-   Add the following parameters the end of the URL ``?rel=0&showinfo=0``.
-   This disables the video title and related video suggestions.
-
--  Screenshots or animations should be proceeded by a sentence
+-  Make sure the screenshot does not contain copyrighted material (preferable),
+   or the license is allowed in our documentation and clearly stated.
+
+-  If taking a png screenshot, use the Firefox or Chrome developer tools to do the following:
+
+   - set the browser viewport to 1280x720 pixels
+   - set the device pixel ratio to 1:1 (i.e., non-hidpi, non-retina)
+   - screenshot the entire *viewport* using the browser developer tools. Screenshots should
+     not include any browser elements such as the browser address bar, browser title bar, etc.,
+     and should not contain any desktop background.
+
+-  If creating a movie, adjust the settings as above (1280x720 viewport resolution, non-hidpi)
+   and use a screen capture utility of your choice to capture just the browser viewport.
+
+-  For PNGs, reduce their size using ``pngquant --speed 1 <filename>``. The
+   resulting filename will have ``-fs8`` appended, so make sure to rename it and
+   use the resulting file. Commit the optimized png file to the main repository.
+   Each png file should be no more than a few hundred kilobytes.
+
+-  For movies, upload them to the IPython/Jupyter YouTube channel and add them
+   to the `jupyterlab-media <https://github.com/jupyterlab/jupyterlab-media>`__
+   repository. To embed a movie in the documentation, use the
+   ``www.youtube-nocookie.com`` website, which can be found by clicking on the
+   'privacy-enhanced' embedding option in the Share dialog on YouTube. Add the
+   following parameters the end of the URL ``?rel=0&amp;showinfo=0``. This
+   disables the video title and related video suggestions.
+
+-  Screenshots or animations should be preceded by a sentence
    describing the content, such as "To open a file, double-click on its
    name in the File Browser:".
 

docs/source/developer/extension_dev.rst

@@ -16,7 +16,7 @@ JupyterLab can be extended in four ways via:
    extend the functionality of document widgets added to the
    application, and we cover them in :ref:`documents`.
 
-See :ref:`xkcd_extension_tutorial` to learn how to make a simple JupyterLab extension.
+See :ref:`extension_tutorial` to learn how to make a simple JupyterLab extension.
 
 A JupyterLab application is comprised of:
 

docs/source/index.rst

@@ -60,7 +60,7 @@ JupyterLab is the next-generation web-based user interface for Project Jupyter.
    developer/examples
    developer/ui_helpers
    developer/terminology
-   developer/xkcd_extension_tutorial
+   developer/extension_tutorial
 
 Indices and Tables
 ------------------