From ef81096f693dce297aeba9fff382c2c8d29dac4e Mon Sep 17 00:00:00 2001 From: "C. E. Ball" Date: Wed, 29 Nov 2017 01:11:13 +0000 Subject: [PATCH 1/4] Initial pass at website. --- .travis.yml | 41 +++++++++++++++ ...atures.ipynb => Additional_Features.ipynb} | 0 doc/{index.ipynb => Overview.ipynb} | 0 doc/conf.py | 43 ++++++++++++++++ doc/index.rst | 50 +++++++++++++++++++ doc/latest_news.html | 4 ++ etc/travis-miniconda.sh | 9 ++++ 7 files changed, 147 insertions(+) create mode 100644 .travis.yml rename doc/{AdditionalFeatures.ipynb => Additional_Features.ipynb} (100%) rename doc/{index.ipynb => Overview.ipynb} (100%) create mode 100644 doc/conf.py create mode 100644 doc/index.rst create mode 100644 doc/latest_news.html create mode 100644 etc/travis-miniconda.sh diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..748e043 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,41 @@ +language: generic + +os: + - linux + +sudo: false + +stages: + - name: docs + if: branch = docs + +# TODO: stage=docs (above) only on tag once initial version is +# up. Same for gh pages deploy section (at the bottom). + +jobs: + include: + - stage: docs + env: PYTHON_VERSION="3.6" + install: + - source ./etc/travis-miniconda.sh + - conda create -n test-environment python=$PYTHON_VERSION + - source activate test-environment + - conda install param ipywidgets + - conda install -c conda-forge notebook ipython sphinx beautifulsoup4 graphviz selenium phantomjs + - pip install nbsite sphinx_ioam_theme + - pip install -e . + script: + - cd doc + - nbsite_nbpagebuild.py ioam paramnb . . + - sphinx-build -b html . ./_build/html + - nbsite_fix_links.py _build/html + - touch ./_build/html/.nojekyll + - nbsite_cleandisthtml.py ./_build/html take_a_chance + +deploy: + provider: pages + skip_cleanup: true + github_token: $GITHUB_TOKEN + local_dir: ./_build/html + on: + branch: docs diff --git a/doc/AdditionalFeatures.ipynb b/doc/Additional_Features.ipynb similarity index 100% rename from doc/AdditionalFeatures.ipynb rename to doc/Additional_Features.ipynb diff --git a/doc/index.ipynb b/doc/Overview.ipynb similarity index 100% rename from doc/index.ipynb rename to doc/Overview.ipynb diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..30c4506 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,43 @@ +# -*- coding: utf-8 -*- + +from nbsite.shared_conf import * + +################################################### +# edit things below as appropriate for your project + +project = u'ParamNB' +authors = u'ParamNB GitHub contributors' +copyright = u'2017 ' + authors +description = 'Automatically generate ipywidgets from Parameterized objects in a Jupyter notebook.' + +import paramnb +version = release = str(paramnb.__version__) + +html_static_path += ['_static'] +html_theme = 'sphinx_ioam_theme' +# logo file etc should be in html_static_path, e.g. _static +html_theme_options = { +# 'custom_css':'bettercolors.css', +# 'logo':'amazinglogo.png', +# 'favicon':'amazingfavicon.ico' +} + +_NAV = ( +) + +html_context.update({ + 'PROJECT': project, + 'DESCRIPTION': description, + 'AUTHOR': authors, + # will work without this - for canonical (so can ignore when building locally or test deploying) + 'WEBSITE_SERVER': 'https://ioam.github.io/paramnb', + 'VERSION': version, + 'NAV': _NAV, + # by default, footer links are same as those in header + 'LINKS': _NAV, + 'SOCIAL': ( + ('Gitter', '//gitter.im/ioam/holoviews'), + ('Twitter', '//twitter.com/holoviews'), + ('Github', '//github.com/ioam/paramnb'), + ) +}) diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..88df838 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,50 @@ +******* +ParamNB +******* + +.. raw:: html + +
+ + +**Automatically generate ipywidgets from Parameterized objects in a Jupyter notebook** + +Project is an `open-source +`_ Python +library for something something something something and something +more. + +Please feel free to report `issues +`_ or `contribute code +`_. You are also +welcome to chat with the developers on `gitter +`_. + + +.. raw:: html + +
+ + +.. raw:: html + :file: latest_news.html + + +.. raw:: html + +
+ +
+ +
+ + + +.. toctree:: + :hidden: + :maxdepth: 2 + + Introduction + Overview + Additional Features + JSONInit diff --git a/doc/latest_news.html b/doc/latest_news.html new file mode 100644 index 0000000..be91639 --- /dev/null +++ b/doc/latest_news.html @@ -0,0 +1,4 @@ +
+ +
+ diff --git a/etc/travis-miniconda.sh b/etc/travis-miniconda.sh new file mode 100644 index 0000000..4133c7f --- /dev/null +++ b/etc/travis-miniconda.sh @@ -0,0 +1,9 @@ +if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then + wget https://repo.continuum.io/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -O miniconda.sh; +else + wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh; +fi +bash miniconda.sh -b -p $HOME/miniconda +export PATH="$HOME/miniconda/bin:$PATH" +conda config --set always_yes yes --set changeps1 no +conda update conda From ac4db3c0ef491cac017d084ddcd8769f668b0c7e Mon Sep 17 00:00:00 2001 From: "C. E. Ball" Date: Wed, 29 Nov 2017 01:12:43 +0000 Subject: [PATCH 2/4] Oops, docs branch already used. --- .travis.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.travis.yml b/.travis.yml index 748e043..e0c9215 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,7 +7,7 @@ sudo: false stages: - name: docs - if: branch = docs + if: branch = docs2 # TODO: stage=docs (above) only on tag once initial version is # up. Same for gh pages deploy section (at the bottom). @@ -38,4 +38,4 @@ deploy: github_token: $GITHUB_TOKEN local_dir: ./_build/html on: - branch: docs + branch: docs2 From 043791e09d5d78d95863918483828c3819805cb4 Mon Sep 17 00:00:00 2001 From: "C. E. Ball" Date: Wed, 29 Nov 2017 01:20:30 +0000 Subject: [PATCH 3/4] Removed user-/site-specific junk. --- doc/Additional_Features.ipynb | 55 ++++------------- doc/JSONInit.ipynb | 79 ++++++------------------ doc/Overview.ipynb | 111 +++++----------------------------- 3 files changed, 44 insertions(+), 201 deletions(-) diff --git a/doc/Additional_Features.ipynb b/doc/Additional_Features.ipynb index 7483b96..70935db 100644 --- a/doc/Additional_Features.ipynb +++ b/doc/Additional_Features.ipynb @@ -3,9 +3,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": true - }, + "metadata": {}, "outputs": [], "source": [ "import param\n", @@ -24,9 +22,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": true - }, + "metadata": {}, "outputs": [], "source": [ "class TooltipExample(param.Parameterized):\n", @@ -36,9 +32,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": true - }, + "metadata": {}, "outputs": [], "source": [ "paramnb.Widgets(TooltipExample)" @@ -56,9 +50,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": true - }, + "metadata": {}, "outputs": [], "source": [ "class Location(param.Parameterized):\n", @@ -75,9 +67,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": true - }, + "metadata": {}, "outputs": [], "source": [ "paramnb.Widgets(Task)" @@ -86,9 +76,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": true - }, + "metadata": {}, "outputs": [], "source": [ "Task.employee.location.duration" @@ -113,9 +101,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": true - }, + "metadata": {}, "outputs": [], "source": [ "import numpy as np\n", @@ -125,9 +111,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": true - }, + "metadata": {}, "outputs": [], "source": [ "class HTMLExample(param.Parameterized):\n", @@ -155,9 +139,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": true - }, + "metadata": {}, "outputs": [], "source": [ "import holoviews as hv\n", @@ -189,30 +171,15 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": true - }, + "metadata": {}, "outputs": [], "source": [] } ], "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.6.0" + "pygments_lexer": "ipython3" } }, "nbformat": 4, diff --git a/doc/JSONInit.ipynb b/doc/JSONInit.ipynb index cc696b7..16ec71d 100644 --- a/doc/JSONInit.ipynb +++ b/doc/JSONInit.ipynb @@ -26,9 +26,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "import os\n", @@ -59,9 +57,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "os.environ['PARAMNB_INIT']" @@ -77,9 +73,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "class Test(param.Parameterized):\n", @@ -97,9 +91,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "paramnb.Widgets(Test, initializer=paramnb.JSONInit())" @@ -128,9 +120,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "os.environ['TARGETED']" @@ -146,9 +136,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "class Target1(param.Parameterized):\n", @@ -170,9 +158,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "paramnb.Widgets(Target1, initializer=paramnb.JSONInit(varname='TARGETED'))" @@ -190,9 +176,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "paramnb.Widgets(Target2, initializer=paramnb.JSONInit(varname='TARGETED'))" @@ -200,9 +184,7 @@ }, { "cell_type": "markdown", - "metadata": { - "collapsed": true - }, + "metadata": {}, "source": [ "## Example 3" ] @@ -224,9 +206,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "os.environ['CUSTOM']" @@ -235,9 +215,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "class Example(param.Parameterized):\n", @@ -265,9 +243,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "import json\n", @@ -289,9 +265,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "os.environ['PARAMNB_INIT']" @@ -300,9 +274,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false - }, + "metadata": {}, "outputs": [], "source": [ "class Test(param.Parameterized):\n", @@ -322,9 +294,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": true - }, + "metadata": {}, "outputs": [], "source": [ "paramnb.Widgets(Test, initializer=paramnb.JSONInit(json_file='param_init.json'))" @@ -332,9 +302,7 @@ }, { "cell_type": "markdown", - "metadata": { - "collapsed": true - }, + "metadata": {}, "source": [ "## Tips" ] @@ -355,22 +323,9 @@ } ], "metadata": { - "kernelspec": { - "display_name": "Python 2", - "language": "python", - "name": "python2" - }, "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 2 - }, - "file_extension": ".py", - "mimetype": "text/x-python", "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython2", - "version": "2.7.12" + "pygments_lexer": "ipython3" } }, "nbformat": 4, diff --git a/doc/Overview.ipynb b/doc/Overview.ipynb index 6750e0e..5447928 100644 --- a/doc/Overview.ipynb +++ b/doc/Overview.ipynb @@ -2,15 +2,7 @@ "cells": [ { "cell_type": "markdown", - "metadata": { - "deletable": true, - "editable": true, - "urth": { - "dashboard": { - "hidden": true - } - } - }, + "metadata": {}, "source": [ "[ParamNB](https://github.com/ioam/paramnb) is a small library that represents Parameters graphically in a Jupyter notebook. Parameters are Python attributes extended using the [Param library](https://github.com/ioam/param) to support types, ranges, and documentation, which turns out to be just the information you need to automatically create widgets for each parameter. ParamNB currently uses [ipywidgets](https://ipywidgets.readthedocs.io) to display the widgets, but the design of Param and ParamNB allows your code to be completely independent of the underlying widgets library, and ParamNB can be updated to use other widget libraries as they are developed without needing changes in your code.\n", "\n", @@ -22,11 +14,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false, - "deletable": true, - "editable": true - }, + "metadata": {}, "outputs": [], "source": [ "import param\n", @@ -67,10 +55,7 @@ }, { "cell_type": "markdown", - "metadata": { - "deletable": true, - "editable": true - }, + "metadata": {}, "source": [ "As you can see, declaring Parameters depends only on the separate Param library. Parameters are a simple idea with some properties that are crucial for helping you create clean, usable code:\n", "\n", @@ -84,16 +69,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false, - "deletable": true, - "editable": true, - "urth": { - "dashboard": { - "hidden": true - } - } - }, + "metadata": {}, "outputs": [], "source": [ "import paramnb\n", @@ -102,10 +78,7 @@ }, { "cell_type": "markdown", - "metadata": { - "deletable": true, - "editable": true - }, + "metadata": {}, "source": [ "As you can see, `paramnb.Widgets()` does not need to be provided with any knowledge of your domain-specific application, not even the names of your parameters; it simply displays widgets for whatever Parameters may have been defined on that object. Using Param with ParamNB thus achieves a nearly complete separation between your domain-specific code and your display code, making it vastly easier to maintain both of them over time. Here even the `msg` button behavior was specified declaratively, as an action that can be invoked (printing \"Hello\") independently of whether it is used in a GUI or other context.\n", "\n", @@ -117,11 +90,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false, - "deletable": true, - "editable": true - }, + "metadata": {}, "outputs": [], "source": [ "Example.unbounded_int" @@ -130,11 +99,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false, - "deletable": true, - "editable": true - }, + "metadata": {}, "outputs": [], "source": [ "Example.num_int" @@ -143,11 +108,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false, - "deletable": true, - "editable": true - }, + "metadata": {}, "outputs": [], "source": [ "#Example.print_param_defaults() # see all parameter values" @@ -155,10 +116,7 @@ }, { "cell_type": "markdown", - "metadata": { - "deletable": true, - "editable": true - }, + "metadata": {}, "source": [ "As you can see, you can access the parameter values at the class level from within the notebook to control behavior explicitly, e.g. to select what to show in subsequent cells. Moreover, any instances of the Parameterized classes in your own code will now use the new parameter values unless specifically overridden in that instance, so you can now import and use your domain-specific library however you like, knowing that it will use your interactive selections wherever those classes appear. None of the domain-specific code needs to know or care that you used ParamNB; it will simply see new values for whatever attributes were changed interactively. ParamNB thus allows you to provide notebook-specific, domain-specific interactive functionality without ever tying your domain-specific code to the notebook environment.\n", "\n", @@ -191,11 +149,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false, - "deletable": true, - "editable": true - }, + "metadata": {}, "outputs": [], "source": [ "class Example2(param.Parameterized):\n", @@ -208,11 +162,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false, - "deletable": true, - "editable": true - }, + "metadata": {}, "outputs": [], "source": [ "Example2.num1, Example2.number2" @@ -220,10 +170,7 @@ }, { "cell_type": "markdown", - "metadata": { - "deletable": true, - "editable": true - }, + "metadata": {}, "source": [ "Notice that in a live notebook, the `In` and `Out` numbers of the above cell increase every time you release a slider after dragging it, because that cell is being re-executed. \n", "\n", @@ -233,11 +180,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false, - "deletable": true, - "editable": true - }, + "metadata": {}, "outputs": [], "source": [ "paramnb.Widgets(Example2,button=True,callback=hello,next_n=1)" @@ -246,11 +189,7 @@ { "cell_type": "code", "execution_count": null, - "metadata": { - "collapsed": false, - "deletable": true, - "editable": true - }, + "metadata": {}, "outputs": [], "source": [ "Example2.num1, Example2.number2" @@ -258,10 +197,7 @@ }, { "cell_type": "markdown", - "metadata": { - "deletable": true, - "editable": true - }, + "metadata": {}, "source": [ "Here, the cell above changes its number (and output value) only when the \"Run 1\" button is pressed in the previous cell. The supplied callback is also executed at that time.\n", "\n", @@ -274,24 +210,9 @@ } ], "metadata": { - "anaconda-cloud": {}, - "hide_input": false, - "kernelspec": { - "display_name": "Python [default]", - "language": "python", - "name": "python2" - }, "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 2 - }, - "file_extension": ".py", - "mimetype": "text/x-python", "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython2", - "version": "2.7.11" + "pygments_lexer": "ipython3" } }, "nbformat": 4, From 031d7ed168fea8368ec58ab50fc5136cc7e5fc27 Mon Sep 17 00:00:00 2001 From: "C. E. Ball" Date: Wed, 29 Nov 2017 02:04:50 +0000 Subject: [PATCH 4/4] Set environment variables for jsoninit. --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index e0c9215..8e362cd 100644 --- a/.travis.yml +++ b/.travis.yml @@ -27,7 +27,7 @@ jobs: script: - cd doc - nbsite_nbpagebuild.py ioam paramnb . . - - sphinx-build -b html . ./_build/html + - PARAMNB_INIT='{"p1":5}' TARGETED='{"Target1":{"p1":3}, "Target2":{"s":"test"}}' CUSTOM='{"custom":{"val":99}}' sphinx-build -b html . ./_build/html - nbsite_fix_links.py _build/html - touch ./_build/html/.nojekyll - nbsite_cleandisthtml.py ./_build/html take_a_chance