Merge pull request #3104 from willingc/doc-landing

Make doc structure more user friendly

Author: jasongrout

docs/source/changelog.md

@@ -1,4 +1,4 @@
-# ipywidgets changelog
+# ipywidgets Changelog
 
 A summary of changes in ipywidgets. For more detailed information, see the issues and pull requests for the appropriate milestone on [GitHub](https://github.com/jupyter-widgets/ipywidgets).
 

docs/source/conf.py

@@ -43,7 +43,7 @@
 
 master_doc = 'index'
 project = 'Jupyter Widgets'
-copyright = '2017 Project Jupyter'
+copyright = '2017-2021 Project Jupyter'
 author = 'Jupyter Team'
 
 language = None
@@ -103,4 +103,11 @@
 # -- Theme options -----------------
 
 # Options are theme-specific and customize the look and feel of the theme.
-html_theme_options = {}
+html_theme_options = {
+    # Toc options
+    'collapse_navigation': True,
+    'sticky_navigation': True,
+    'navigation_depth': 2,
+    'includehidden': True,
+    'titles_only': False
+}

docs/source/dev_docs.md

@@ -1,19 +1,11 @@
-Building the Documentation
-==========================
+# Develop and Build Documentation
 
-To build the documentation you'll need [Sphinx](http://www.sphinx-doc.org/), [pandoc](http://pandoc.org/)
+To build the documentation you'll need [Sphinx](http://www.sphinx-doc.org/)
 and a few other packages.
 
-First create a [conda environment](http://conda.pydata.org/docs/using/envs.html#use-environment-from-file) named `ipywidgets_docs` to install all the necessary packages:
+## Setup docs dev environment
 
-```bash
-# create the environment
-conda create -n ipywidgets_docs -c conda-forge python pip
-
-# activate the environment
-conda activate ipywidgets_docs   # Linux and OS X
-activate ipywidgets_docs         # Windows
-```
+### Use pip
 
 Alternatively, it is also possible to create a virtual environment and activate it with the following commands:
 
@@ -31,6 +23,27 @@ In the environment, install the packages:
 python -m pip install -r docs/requirements.txt
 ```
 
+### Use conda
+
+First create a [conda environment](http://conda.pydata.org/docs/using/envs.html#use-environment-from-file) named `ipywidgets_docs` to install all the necessary packages:
+
+```bash
+# create the environment
+conda create -n ipywidgets_docs -c conda-forge python pip
+```
+
+Use conda to install the packages listed in `docs/requirements.txt`.
+
+Then, activate the conda environment.
+
+```bash
+# activate the environment
+conda activate ipywidgets_docs   # Linux and OS X
+activate ipywidgets_docs         # Windows
+```
+
+## Build the documentation
+
 Once you have installed the required packages, you can build the docs with:
 
 ```bash
@@ -40,15 +53,22 @@ make html
 ```
 
 After that, the generated HTML files will be available at
-`build/html/index.html`. You may view the docs in your browser.
+`build/html/index.html`. You may view the docs in your browser by entering
+the following in the terminal: `open build/html/index.html`. Alternatively,
+you can start a webserver using `python3 -m http.server` and navigate to
+<http://localhost:8000/build/html/index.html>.
 
 Windows users can find `make.bat` in the `docs` folder.
 
 You should also have a look at the [Project Jupyter Documentation Guide](https://jupyter.readthedocs.io/en/latest/contrib_docs/index.html).
 
-### Cleaning notebooks for docs
+## Cleaning notebook output for docs
 
-Notebook output and metadata should be stripped with [nbstripoutput](https://github.com/kynan/nbstripout) before commiting. For example:
-```
-nbstripoutput docs/source/examples/Widget\ List.ipynb
+When using notebook source files to generate documentation, it's good practice to strip
+notebook output and metadata with [nbstripout](https://github.com/kynan/nbstripout)
+before committing the notebook. For example, the following command will strip
+all output from a notebook:
+
+```bash
+nbstripout docs/source/examples/Widget\ List.ipynb
 ```

docs/source/developer_docs.rst

@@ -1,5 +1,5 @@
-Developer Docs
-===============
+ipywidgets Development
+======================
 
 The Jupyter widgets packages are developed in the `https://github.com/jupyter-widgets/ipywidgets <https://github.com/jupyter-widgets/ipywidgets>`_ git repository. See the issue tracker, README, and other Github documents for the most recent information.
 
@@ -13,15 +13,3 @@ Scope of ipywidgets
 2. A basic, lightweight set of form controls that *use* this framework, based on standard HTML form controls. These included controls include a text area, text box, select and multiselect controls, checkbox, etc. A few more advanced controls that are very popular are also included, such as a slider and basic tab panels.
 
 The framework for building rich interactive objects is the foremost purpose of the ipywidgets project, and the set of included reference form controls is purposefully kept small and self-contained to serve as something like a reference implementation. We encourage and support a robust ecosystem of packages built on top of the ipywidgets framework to provide more complicated interactive objects, such as maps or 2d and 3d visualizations, or other form control systems built on a variety of popular Javascript frameworks such as Material or Vue.
-
-
-Additional Developer Docs
--------------------------
-
-.. toctree::
-   :maxdepth: 3
-
-   dev_install.md
-   dev_testing.md
-   dev_docs
-   dev_release.md

docs/source/index.rst

@@ -1,11 +1,60 @@
 ipywidgets
 ==========
 
-Full Table of Contents
-----------------------
+.. only:: html
+
+    :Release: |release|
+    :Date: |today|
+
+**ipywidgets**, also known as jupyter-widgets or simply widgets, are
+`interactive HTML widgets <https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb>`_
+for Jupyter notebooks and the IPython kernel.
+
+Notebooks come alive when interactive widgets are used. Users gain control of
+their data and can visualize changes in the data.
+
+Learning becomes an immersive, fun experience. Researchers can easily see
+how changing inputs to a model impact the results. We hope you will add
+ipywidgets to your notebooks, and we're here to help you get started.
+
 
 .. toctree::
-    :maxdepth: 2
+    :caption: User Guide
+    :maxdepth: 1
+
+    user_install.md
+    examples/Widget Basics.ipynb
+    examples/Widget List.ipynb
+    examples/Output Widget.ipynb
+    examples/Widget Events.ipynb
+    examples/Widget Styling.ipynb
+    examples/Layout Templates.ipynb
+    examples/Widget Custom.ipynb
+    examples/Using Interact.ipynb
+    examples/Widget Low Level.ipynb
+    examples/Widget Asynchronous.ipynb
+    embedding.md
+
+.. toctree::
+   :caption: Changelog and Migration
+   :maxdepth: 1
+
+   changelog.md
+   migration_guides.md
+
+.. toctree::
+   :caption: Developer Guide
+   :maxdepth: 1
+
+   developer_docs
+   dev_install.md
+   dev_testing.md
+   dev_docs.md
+   contributing.md
+   dev_release.md
+
+.. only:: html
 
-    user_guide
-    developer_docs
+  * :ref:`genindex`
+  * :ref:`modindex`
+  * :ref:`search`