Merge pull request #3739 from jzf2101/ui_names

Reviewed UI Names and Spelling

CONTRIBUTING.md

@@ -16,7 +16,7 @@ questions about these issues.
 ## General Guidelines
 
 For general documentation about contributing to Jupyter projects, see the
-[Project Jupyter Contributor Documentation](https://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html).
+[Project Jupyter Contributor Documentation](https://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html) and [Code of Conduct](https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md).
 
 All source code is written in [TypeScript](http://www.typescriptlang.org/Handbook). See the [Style Guide](https://github.com/jupyterlab/jupyterlab/wiki/TypeScript-Style-Guide).
 
@@ -108,6 +108,8 @@ server extension:
 jupyter serverextension enable --py --sys-prefix jupyterlab
 ```
 
+For installation instructions to write documentation, please see [Writing Documentation](#writing-documentation)
+
 ### Run JupyterLab
 
 Start JupyterLab in development mode:
@@ -121,7 +123,7 @@ built in the dev-installed Python package.  When running in dev mode, a red
 stripe will appear at the top of the page; this is to indicate running
 an unreleased version.
 
-### Build and run the tests
+### Build and Run the Tests
 
 ```bash
 jlpm run build:test
@@ -175,7 +177,6 @@ To run a specific example, change to the examples directory (i.e.
 ```bash
 python main.py
 ```
-
 ## Debugging
 
 All methods of building JupyterLab produce source maps.  The source maps
@@ -192,8 +193,7 @@ debugging.
 When running a test, the packages will be available at the top level
 (e.g. `application/src`), and the current set of test files available under
 `/src`.  Note: it is recommended to use `jlpm run watch` in the test folder
-while debugging (see [above](#Build and run the tests) for more info) on
-test options.
+while debugging test options.  See [above](#build-and-run-the-tests) for more info.
 
 
 ----
@@ -230,6 +230,35 @@ jlpm run clean
 jlpm run build:packages
 ```
 
+## [Writing Documentation](#writing-documenation)
+
+Documentation is written in Markdown and reStructuredText.  In particular, the documentation on our Read the Docs page is written in reStructuredText. To ensure that the Read the Docs page builds, you'll need to install the documentation dependencies with `conda`.  These dependencies are located in `docs/environment.yml`.  You can install the dependencies for building the documentation by creating a new conda environment:
+
+```bash
+conda env create -f docs/environment.yml
+```
+
+The Developer Documentation includes a [guide](http://jupyterlab.readthedocs.io/en/latest/developer/documentation.html) to writing documentation including writing style, naming conventions, keyboard shortcuts, and screenshots.
+
+To test the docs run:
+
+```
+py.test --check-links -k .md . || py.test --check-links -k .md --lf .
+```
+
+The Read the Docs pages can be built using `make`:
+
+```bash
+cd docs
+make html
+```
+
+Or with `jlpm`:
+
+```
+jlpm run docs
+```
+
 ## The Jupyter Server Extension
 
 The Jupyter server extension source files are in the `jupyterlab/`

docs/source/developer/documentation.rst

@@ -2,7 +2,7 @@ Writing Documentation
 ---------------------
 
 This section provide information about writing documentation for
-JupyterLab.
+JupyterLab.  See  our [Contributor Guide](https://github.com/jupyterlab/jupyterlab/blob/master/CONTRIBUTING.md) for details on installation and testing.
 
 Writing Style
 ~~~~~~~~~~~~~
@@ -61,6 +61,7 @@ The majority of names are written in lower case.  These names include:
 - file browser
 - command palette
 - cell inspector
+- code console
 
 
 The following sections of the user interface should be in title case, directly quoting a word in the UI:
@@ -69,6 +70,7 @@ The following sections of the user interface should be in title case, directly q
 - Files tab
 - Running panel
 - Tabs panel
+- Single-Document Mode
 
 The capitalized words match the label of the UI element the user is clicking on
 because there does not exist a good colloquial name for the tool,

docs/source/developer/documents.rst

@@ -1,3 +1,5 @@
+.. _documents:
+
 Documents
 ---------
 
@@ -5,12 +7,12 @@ JupyterLab can be extended in two ways via:
 
 -  Extensions (top level): Application extensions extend the
    functionality of JupyterLab itself, and we cover them in the
-   `Extensions <extension_dev.md>`__ developer tutorial.
--  **document widget extensions (lower level):** Document widget
+   :ref:`developer_extensions`.
+-  **Document widget extensions (lower level):** Document widget
    extensions extend the functionality of document widgets added to the
    application, and we cover them in this section.
 
-For this section, the term, 'document', refers to any visual thing that
+For this section, the term 'document' refers to any visual thing that
 is backed by a file stored on disk (i.e. uses Contents API).
 
 The `Document

docs/source/developer/extension_dev.rst

@@ -12,7 +12,7 @@ JupyterLab can be extended in three ways via:
    potentially render files of a given type.
 -  document widget extensions (lower level): Document widget extensions
    extend the functionality of document widgets added to the
-   application, and we cover them in the "Documents" tutorial.
+   application, and we cover them in :ref:`documents`.
 
 See :ref:`xkcd_extension_tutorial` to learn how to make a simple JupyterLab extension.
 

docs/source/user/commands.rst

@@ -11,7 +11,7 @@ any JupyterLab command:
 
 [screenshot]
 
-The Command Palette can be accessed using the keyboard shortcut
+The command palette can be accessed using the keyboard shortcut
 Command-Shift-C:
 
 [animation]

docs/source/user/extensions.rst

@@ -29,8 +29,8 @@ Installing Extensions
 ~~~~~~~~~~~~~~~~~~~~~
 
 The base JupyterLab application includes a core set of extensions, which
-provide the features described in this User Guide (Notebook, Terminal,
-Text Editor, etc.) You can install new extensions into the application
+provide the features described in this user guide (notebook, terminal,
+text editor, etc.) You can install new extensions into the application
 using the command:
 
 .. code:: bash
@@ -51,7 +51,7 @@ tarball, or a URL to a gzipped tarball.
 
 We encourage extension authors to add the ``jupyterlab-extensions``
 GitHub topic to any repository with a JupyterLab extension to facilitate
-discovery. You can see a list of extensions by searching Github for the
+discovery. You can see a list of extensions by searching GitHub for the
 `jupyterlab-extension <https://github.com/search?utf8=%E2%9C%93&q=topic%3Ajupyterlab-extension&type=Repositories>`__
 topic.
 

docs/source/user/file_editor.rst

@@ -1,14 +1,14 @@
 .. _file_editor:
 
-File Editor
+Text Editor
 -----------
 
-The file editor in JupyterLab enables you to edit text files in
+The text editor in JupyterLab enables you to edit text files in
 JupyterLab:
 
 [screenshot]
 
-The file editor includes syntax highlighting, configurable indentation
+The text editor includes syntax highlighting, configurable indentation
 (tabs or spaces), different key maps (vim, emacs, Sublime Text) and
 basic theming. These settings can be found in the Settings menu:
 

docs/source/user/file_formats.rst

@@ -58,7 +58,7 @@ the Jupyter Notebook.
 
 Markdown documents can be edited as text files or rendered inline:
 
-[animation showing opening a markdown document editor and renderer
+[animation showing opening a Markdown document editor and renderer
 side-by-side, and changes in the editor being reflected in the renderer]
 
 The Markdown syntax supported in this mode is the same syntax used in
@@ -167,7 +167,7 @@ documentation of Vega or Vega-Lite. JupyterLab supports rendering Vega
 2.x and Vega-Lite 1.x data in files and cell output.
 
 Vega-Lite 1.x files, with a ``.vl`` or ``.vl.json`` file extension, can
-be opened by double-clicking the file in the File Browser:
+be opened by double-clicking the file in the file browser:
 
 [animation]
 
@@ -178,7 +178,7 @@ the “Open With…” submenu in the file browser content menu:
 
 As with other files in JupyterLab, multiple views of a single file
 remain synchronized, allowing you to interactively edit and render
-Vega-Lite/Vega visualizations:
+Vega/Vega-Lite visualizations:
 
 [animation]
 

docs/source/user/files.rst

@@ -27,7 +27,7 @@ You can also drag a file into the main area to create a new tab:
 [animation]
 
 Many files types have :ref:`multiple viewers/editors <file-and-output-formats>`.
-For example, you can open a Markdown file in a text editor or as rendered HTML.
+For example, you can open a Markdown file in a :ref:`text editor <file_editor>` or as rendered HTML.
 A JupyterLab extension can also add new viewers/editors for files.
 To open a file in a non-default viewer/editor, right-click on its name in the
 file browser and use the "Open With..." submenu to select the viewer/editor:

docs/source/user/interface.rst

@@ -25,16 +25,16 @@ The menu bar at the top of JupyterLab has top-level menus that expose
 actions available in JupyterLab with their keyboard shortcuts. The
 default menus are:
 
--  File: actions related to files and directories
--  Edit: actions related to editing documents and other activities
--  View: actions that alter the appearance of JupyterLab
--  Run: actions for running code in different activities such as
-   Notebooks and Code Consoles
--  Kernel: actions for managing kernels, which are separate processes
+-  **File**: actions related to files and directories
+-  **Edit**: actions related to editing documents and other activities
+-  **View**: actions that alter the appearance of JupyterLab
+-  **Run**: actions for running code in different activities such as
+   notebooks and code consoles
+-  **Kernel**: actions for managing kernels, which are separate processes
    for running code
--  Tabs: a list of the open documents and activities in the dock panel
--  Settings: common settings and an advanced settings editor
--  Help: a list of JupyterLab and kernel help links
+-  **Tabs**: a list of the open documents and activities in the dock panel
+-  **Settings**: common settings and an advanced settings editor
+-  **Help**: a list of JupyterLab and kernel help links
 
 :ref:`JupyterLab extensions <user_extensions>` can also create new top-level menus in the menu
 bar.
@@ -60,8 +60,8 @@ JupyterLab extensions can add additional panels to the left sidebar.
 
 .. _main_area:
 
-Main area
-~~~~~~~~~
+Main Work Area
+~~~~~~~~~~~~~~
 
 The main work area in JupyterLab allows you to arrange documents
 (notebooks, text files, etc.) and other activities (terminals, code
@@ -69,12 +69,12 @@ consoles, etc.) into panels of tabs that can be resized or subdivided:
 
 [animation]
 
-The main area has a single current activity. The tab for this activity
+The work area has a single current activity. The tab for this activity
 is marked with a colored top border (blue by default).
 
 .. _tabs:
 
-Tabs and Single Document Mode
+Tabs and Single-Document Mode
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Tabs panel in the left sidebar lists the open documents or
@@ -83,18 +83,18 @@ activities in the main area:
 .. image:: images/interface_tabs.png
    :align: center
 
-The same information is also available in the Tabs Menu:
+The same information is also available in the Tabs menu:
 
 .. image:: images/interface_tabs_menu.png
    :align: center
 
 It is often useful to focus on a single document or activity without
-closing other tabs in the main area. Single Document Mode toggles the
+closing other tabs in the main area. Single-Document Mode toggles the
 view of the main area to show only a single tab at a time:
 
 [animation]
 
-When you leave Single Document Mode, the original layout of the main
+When you leave Single-Document Mode, the original layout of the main
 area is restored.
 
 Context Menus

docs/source/user/notebook.rst

@@ -28,7 +28,7 @@ from the context menu:
 
 [animation]
 
-The user interface for Notebooks in JupyterLab closely follows that of
+The user interface for notebooks in JupyterLab closely follows that of
 the classic Jupyter Notebook. The keyboard shortcuts of the classic
 Notebook continue to work (with command and edit mode). However, a
 number of new things are possible with notebooks in JupyterLab.
@@ -45,7 +45,7 @@ Create multiple synchronized views of a single notebook:
 
 [animation]
 
-Collapse and expand code and output using the View Menu or the blue
+Collapse and expand code and output using the View menu or the blue
 collapser button on left of each cell:
 
 [animation]