[WIP] Major revamp of documentation (#196)

* Docs WIP

* add user docs

* start operator docs

* [wip] more docs

* rearrage some developer docs

* more docs

* update readme

* switch to pydata theme

* minor changes to docs

* update extending docs

* update docs

* minor typo

CONTRIBUTING.rst

@@ -1,5 +1,5 @@
-Contributing to the Jupyter Server
-==================================
+General Jupyter contributor guidelines
+======================================
 
 If you're reading this section, you're probably interested in contributing to
 Jupyter.  Welcome and thanks for your interest in contributing!
@@ -8,19 +8,16 @@ Please take a look at the Contributor documentation, familiarize yourself with
 using the Jupyter Server, and introduce yourself on the mailing list and
 share what area of the project you are interested in working on.
 
-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
 
 Setting Up a Development Environment
-------------------------------------
+====================================
 
 Installing the Jupyter Server
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------
 
 Once you have installed the dependencies mentioned above, use the following
 steps::
@@ -39,7 +36,7 @@ from any directory in your system with::
     jupyter server
 
 Troubleshooting the Installation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------
 
 If you do not see that your Jupyter Server is not running on dev mode, it's possible that you are
 running other instances of Jupyter Server. You can try the following steps:
@@ -54,10 +51,7 @@ running other instances of Jupyter Server. You can try the following steps:
 5. Verify the installation with the steps in the previous section.
 
 Running Tests
--------------
-
-Python Tests
-^^^^^^^^^^^^
+=============
 
 Install dependencies::
 
@@ -67,12 +61,8 @@ To run the Python tests, use::
 
     pytest
 
-If you want coverage statistics as well, you can run::
-
-    py.test --cov notebook -v
-
-Building the Documentation
---------------------------
+Building the Docs
+=================
 
 To build the documentation you'll need `Sphinx <http://www.sphinx-doc.org/en/master/>`_,
 `pandoc <https://pandoc.org/>`_ and a few other packages.

README.md

@@ -1,25 +1,13 @@
 # Jupyter Server
 
-[![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)
 [![Build Status](https://github.com/jupyter/jupyter_server/workflows/CI/badge.svg)](https://github.com/jupyter/jupyter_server/actions)
 [![Documentation Status](https://readthedocs.org/projects/jupyter-server/badge/?version=latest)](http://jupyter-server.readthedocs.io/en/latest/?badge=latest)
 
-The Jupyter Server provides the backend for Jupyter web applications such as
-the Jupyter notebook and JupyterLab.
+The Jupyter Server provides the backend (i.e. the core services, APIs, and REST endpoints) for Jupyter web applications like Jupyter notebook, JupyterLab, and Voila.
 
-**jupyter_server is an early developer preview, and is not suitable for general
-usage yet. Features and implementation are subject to change. Please use the
-stable [notebook server](https://github.com/jupyter/notebook) for production
-usecases.**
+For more information, read our [documentation here](http://jupyter-server.readthedocs.io/en/latest/?badge=latest).
 
-Read more on the Jupyter Server [roadmap](https://github.com/jupyter/jupyter_server/issues/127).
-
-## Installation
-
-You can find the installation documentation for the
-[Jupyter platform, on ReadTheDocs](https://jupyter.readthedocs.io/en/latest/install.html).
-The documentation for advanced usage of Jupyter notebook can be found
-[here](https://jupyter-server.readthedocs.io/en/latest/).
+## Installation and Basic usage
 
 To install the latest release locally, make sure you have
 [pip installed](https://pip.readthedocs.io/en/stable/installing/) and run:
@@ -54,34 +42,18 @@ Launch with:
 
     $ jupyter server
 
-### Running in a remote installation
-
-You need some configuration before starting Jupyter server remotely. See [Running a Jupyter server](http://jupyter-server.readthedocs.io/en/stable/public_server.html).
-
-## Development Installation
-
-See [`CONTRIBUTING.rst`](CONTRIBUTING.rst) for how to set up a local development installation.
-
 ## Contributing
 
 If you are interested in contributing to the project, see [`CONTRIBUTING.rst`](CONTRIBUTING.rst).
 
-## Weekly Dev Meeting
-
-We have videoconference meetings every week where we discuss what we have been working on and get feedback from one another.
-
-Anyone is welcome to attend, if they would like to discuss a topic or just to listen in.
+## Team Meetings and Roadmap
 
 When: Thursdays [8:00am, Pacific time](https://www.thetimezoneconverter.com/?t=8%3A00%20am&tz=San%20Francisco&)
 Where: [calpoly/jupyter Zoom](https://zoom.us/my/jovyan)
 What: [Meeting notes](https://github.com/jupyter/jupyter_server/issues/126)
 
-## Resources
+* When: Thursdays [8:00am, Pacific time](https://www.thetimezoneconverter.com/?t=8%3A00%20am&tz=San%20Francisco&)
+* Where: [Jupyter Zoom](https://calpoly.zoom.us/my/jupyter)
+* What: [Meeting notes](https://github.com/jupyter/jupyter_server/issues/126)
 
-- [Project Jupyter website](https://jupyter.org)
-- [Online Demo at try.jupyter.org](https://try.jupyter.org)
-- [Documentation for Jupyter Server](https://jupyter-server.readthedocs.io/en/latest/) [[PDF](https://media.readthedocs.org/pdf/jupyter-server/latest/jupyter-server.pdf)]
-- [Korean Version of Installation](https://github.com/ChungJooHo/Jupyter_Kor_doc/)
-- [Documentation for Project Jupyter](https://jupyter.readthedocs.io/en/latest/index.html) [[PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)]
-- [Issues](https://github.com/jupyter/jupyter-server/issues)
-- [Technical support - Jupyter Google Group](https://groups.google.com/forum/#!forum/jupyter)
+See our tentative [roadmap here](https://github.com/jupyter/jupyter_server/issues/127).

docs/autogen_config.py

@@ -4,14 +4,14 @@
 from jupyter_server.serverapp import ServerApp
 
 header = """\
-.. _config:
+.. _other-full-config:
 
 
 Config file and command line options
 ====================================
 
 The Jupyter Server can be run with a variety of command line arguments.
-A list of available options can be found below in the :ref:`options section 
+A list of available options can be found below in the :ref:`options section
 <options>`.
 
 Defaults for these options can also be set by creating a file named
@@ -29,16 +29,16 @@
 Options
 -------
 
-This list of options can be generated by running the following and hitting 
+This list of options can be generated by running the following and hitting
 enter::
 
-  $ jupyter server --help
+  $ jupyter server --help-all
 
 """
 try:
-    destination = os.path.join(os.path.dirname(__file__), 'source/config.rst')
+    destination = os.path.join(os.path.dirname(__file__), 'source/other/full-config.rst')
 except:
-    destination = os.path.join(os.getcwd(), 'config.rst')
+    destination = os.path.join(os.getcwd(), 'full-config.rst')
 
 with open(destination, 'w') as f:
     f.write(header)

docs/doc-requirements.txt

@@ -1,3 +1,5 @@
 sphinx>=1.3.6
-sphinx-rtd-theme
+git+https://github.com/pandas-dev/pydata-sphinx-theme.git@master
 sphinxcontrib_github_alt
+sphinxcontrib-openapi
+sphinxemoji

docs/environment.yml

@@ -12,3 +12,5 @@ dependencies:
   - Send2Trash
   - prometheus_client
   - sphinxcontrib_github_alt
+  - sphinxcontrib-openapi
+  - sphinxemoji