Merge pull request ipython#302 from willingc/doc-update

Refresh sphinx docs

docs/README_DOC.md

@@ -0,0 +1,59 @@
+# Documenting traitlets
+
+[Documentation for `traitlets`](https://traitlets.readthedocs.io/en/latest/)
+is hosted on ReadTheDocs.
+
+## Build Documentation locally
+
+1. Change directory to documentation root:
+
+           $ cd docs
+
+2. Create environment
+
+   - [**conda**] Create conda env (and install relevant dependencies):
+
+           $ conda env create -f environment.yml
+
+   - [**pip**] Create virtual environment (and install relevant dependencies):
+
+           $ virtualenv traitlets_docs -p python3
+           $ pip install -r requirements.txt
+
+
+3. Activate the newly built environment `traitlets_docs`
+
+   - [**conda**] Activate conda env:
+
+           $ source activate traitlets_docs
+
+   - [**pip**] The virtualenv should have been automatically activated. If
+   not:
+
+           $ source activate
+
+4. Build documentation using Makefile for Linux and OS X:
+
+           $ make html
+
+  or on Windows:
+
+           $ make.bat html
+
+5. Display the documentation locally by navigating to
+   ``build/html/index.html`` in your browser:
+
+   Or alternatively you may run a local server to display
+   the docs. In Python 3:
+
+           $ python -m http.server 8000
+
+   In your browser, go to `http://localhost:8000`.
+
+## Developing Documentation
+
+### Helpful files and directories
+
+* `source/conf.py` - Sphinx build configuration file
+* `source` directory - source for documentation
+* `source/index.rst` - Main landing page of the Sphinx documentation

docs/environment.yml

@@ -0,0 +1,9 @@
+name: traitlets
+channels:
+  - conda-forge
+  - conda
+dependencies:
+  - python=3
+  - ipython-genutils
+  - sphinx
+  - sphinx_rtd_theme

docs/requirements.txt

@@ -1 +1,4 @@
-ipython_genutils
+ipython-genutils
+Sphinx
+sphinx-rtd-theme
+-e ../.

docs/source/conf.py

@@ -313,3 +313,13 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
+
+# Read The Docs
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+# otherwise, readthedocs.org uses their theme by default, so no need to specify it

readthedocs.yml

@@ -0,0 +1,9 @@
+conda:
+    file: docs/environment.yml
+python:
+    version: 3
+    setup_py_install: true
+    pip install: true
+formats:
+    - epub
+    - pdf

traitlets/traitlets.py

@@ -839,7 +839,7 @@ def validate(*names):
     the registered cross validator could potentially make changes to attributes
     of the ``HasTraits`` instance. However, we recommend not to do so. The reason
     is that the cross-validation of attributes may run in arbitrary order when
-    exiting the ``hold_trait_notifications` context, and such changes may not
+    exiting the ``hold_trait_notifications`` context, and such changes may not
     commute.
     """
     if not names: