diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..8e362cd --- /dev/null +++ b/.travis.yml @@ -0,0 +1,41 @@ +language: generic + +os: + - linux + +sudo: false + +stages: + - name: 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). + +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 . . + - 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 + +deploy: + provider: pages + skip_cleanup: true + github_token: $GITHUB_TOKEN + local_dir: ./_build/html + on: + branch: docs2 diff --git a/doc/AdditionalFeatures.ipynb b/doc/Additional_Features.ipynb similarity index 88% rename from doc/AdditionalFeatures.ipynb rename to doc/Additional_Features.ipynb index 7483b96..70935db 100644 --- a/doc/AdditionalFeatures.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/index.ipynb b/doc/Overview.ipynb similarity index 88% rename from doc/index.ipynb rename to doc/Overview.ipynb index 6750e0e..5447928 100644 --- a/doc/index.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, 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