diff --git a/.gitignore b/.gitignore index c31d157f..961aa6ad 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,6 @@ datafile.json # OSX folder metadata *.DS_Store + +# Sphinx documentation +docs/build/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ed58d21..d14002e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,5 @@ -Contributing to the Optimizely Python SDK -========================================= +Contributing +============ We welcome contributions and feedback! All contributors must sign our [Contributor License Agreement @@ -15,7 +15,7 @@ Development process 2. Please follow the [commit message guidelines](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines) for each commit message. 3. Make sure to add tests! -4. Run `pep8` to ensure there are no lint errors. +4. Run `flake8` to ensure there are no lint errors. 5. `git push` your changes to GitHub. 6. Open a PR from your fork into the master branch of the original repo. @@ -34,13 +34,12 @@ Pull request acceptance criteria - Tests are located in `/tests` with one file per class. - Please don't change the `__version__`. We'll take care of bumping the version when we next release. -- Lint your code with PEP-8 before submitting. +- Lint your code with Flake8 before submitting. Style ----- -We enforce Flake8 rules with a few minor -[deviations](https://github.com/optimizely/python-sdk/blob/master/tox.ini). +We enforce Flake8 rules. License ------- diff --git a/MANIFEST.in b/MANIFEST.in index 109cdcd0..286e52fc 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -2,4 +2,5 @@ include LICENSE include CHANGELOG.md include README.md include requirements/* +recursive-exclude docs * recursive-exclude tests * diff --git a/README.md b/README.md index 30c0ede4..16ea39e6 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,10 @@ Optimizely Python SDK ===================== -[![PyPI -version](https://badge.fury.io/py/optimizely-sdk.svg)](https://pypi.org/project/optimizely-sdk) -[![Build -Status](https://travis-ci.org/optimizely/python-sdk.svg?branch=master)](https://travis-ci.org/optimizely/python-sdk) -[![Coverage -Status](https://coveralls.io/repos/github/optimizely/python-sdk/badge.svg)](https://coveralls.io/github/optimizely/python-sdk) -[![Apache -2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0) +[![PyPI version](https://badge.fury.io/py/optimizely-sdk.svg)](https://pypi.org/project/optimizely-sdk) +[![Build Status](https://travis-ci.org/optimizely/python-sdk.svg?branch=master)](https://travis-ci.org/optimizely/python-sdk) +[![Coverage Status](https://coveralls.io/repos/github/optimizely/python-sdk/badge.svg)](https://coveralls.io/github/optimizely/python-sdk) +[![Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0) This repository houses the official Python SDK for use with Optimizely Full Stack and Optimizely Rollouts. @@ -126,21 +122,23 @@ notification_center. #### Advanced configuration The following properties can be set to override the default -configurations for [PollingConfigManager]{.title-ref}. +configurations for [PollingConfigManager](#pollingconfigmanager). - **PropertyName** **Default Value** **Description** - ------------------ ----------------------------------------------------------- -------------------------------------------------------------------------------------- - update_interval 5 minutes Fixed delay between fetches for the datafile - sdk_key None Optimizely project SDK key - url None URL override location used to specify custom HTTP source for the Optimizely datafile - url_template https://cdn.optimizely.com/datafiles/{sdk_key}.json Parameterized datafile URL by SDK key - datafile None Initial datafile, typically sourced from a local cached source +| **Property Name** |**Default Value**| **Description** | +|:-----------------------:|:---------------:|:--------------------------------------------------------------:| +| update_interval | 5 minutes | Fixed delay between fetches for the datafile | +| sdk_key | None | Optimizely project SDK key | +| url | None | URL override location used to specify custom | +| HTTP source for Optimizely datafile
url_template |https://cdn.optimizely.com/datafiles/{sdk_key}.json|Parameterized datafile URL by SDK key| +| datafile | None | Initial datafile, typically sourced from a local cached source | A notification signal will be triggered whenever a *new* datafile is fetched and Project Config is updated. To subscribe to these notifications, use: -`notification_center.add_notification_listener(NotificationTypes.OPTIMIZELY_CONFIG_UPDATE, update_callback)` +``` +notification_center.add_notification_listener(NotificationTypes.OPTIMIZELY_CONFIG_UPDATE, update_callback) +``` For Further details see the Optimizely [Full Stack documentation](https://docs.developers.optimizely.com/full-stack/docs) to learn how to set up your first Python project and use the SDK. @@ -202,4 +200,4 @@ would be: ### Contributing -Please see [CONTRIBUTING](CONTRIBUTING.md). +Please see [CONTRIBUTING](https://github.com/optimizely/python-sdk/blob/master/CONTRIBUTING.md). diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..2c5032fb --- /dev/null +++ b/docs/README.md @@ -0,0 +1,20 @@ +Documentation +============= + +Getting Started +--------------- + +### Installing the requirements + +To install dependencies required to generate sphinx documentation locally, execute the following command from the main directory: + + pip install -r requirements/docs.txt + +### Building documentation locally + +To generate Python SDK documentation locally, execute the following commands: + + cd docs/ + make html + +This will build HTML docs in `docs/build/html/index.html`. Open this file in your web browser to see the docs. \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..6247f7e2 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/optimizely.png b/docs/optimizely.png new file mode 100644 index 00000000..2ab1e6a5 Binary files /dev/null and b/docs/optimizely.png differ diff --git a/docs/source/api_reference.rst b/docs/source/api_reference.rst new file mode 100644 index 00000000..8c525623 --- /dev/null +++ b/docs/source/api_reference.rst @@ -0,0 +1,33 @@ +Optimizely's APIs +================= +.. automodule:: optimizely.optimizely + :members: + :special-members: __init__ + + +Event Dispatcher +================ +.. autoclass:: optimizely.event_dispatcher.EventDispatcher + :members: + + +Logger +====== +.. automodule:: optimizely.logger + :members: + + +User Profile +============ + +``UserProfile`` +--------------- + +.. autoclass:: optimizely.user_profile.UserProfile + :members: + +``UserProfileService`` +---------------------- + +.. autoclass:: optimizely.user_profile.UserProfileService + :members: diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..d212e930 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,64 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('../..')) + +from optimizely.version import __version__ # noqa: E402 + +# -- Project information ----------------------------------------------------- + +project = 'Optimizely Python SDK' +copyright = '2016-2020, Optimizely, Inc' +author = 'Optimizely, Inc.' +version = __version__ +master_doc = 'index' + +# The full version, including alpha/beta/rc tags +release = '' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "m2r", + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx.ext.autosectionlabel" +] +autosectionlabel_prefix_document = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [ +] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +# html_theme = 'alabaster' +html_theme = "sphinx_rtd_theme" +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = ['_static'] +html_logo = "../optimizely.png" diff --git a/docs/source/config_manager.rst b/docs/source/config_manager.rst new file mode 100644 index 00000000..48cdba0d --- /dev/null +++ b/docs/source/config_manager.rst @@ -0,0 +1,20 @@ +Config Manager +============== + +``Base Config Manager`` +----------------------- + +.. autoclass:: optimizely.config_manager.BaseConfigManager + :members: + +``Static Config Manager`` +------------------------- + +.. autoclass:: optimizely.config_manager.StaticConfigManager + :members: + +``Polling Config Manager`` +-------------------------- + +.. autoclass:: optimizely.config_manager.PollingConfigManager + :members: diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 00000000..36431a6a --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1 @@ +.. mdinclude:: ../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..f15044bc --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,26 @@ +Optimizely Python SDK +===================== + +.. toctree:: + :caption: Introduction + + readme + + +.. toctree:: + :caption: API reference + + api_reference + + +.. toctree:: + :caption: Configuration Data + + config_manager + optimizely_config + + +.. toctree:: + :caption: Help + + contributing diff --git a/docs/source/optimizely_config.rst b/docs/source/optimizely_config.rst new file mode 100644 index 00000000..7625be0a --- /dev/null +++ b/docs/source/optimizely_config.rst @@ -0,0 +1,5 @@ +OptimizelyConfig +================ + +.. automodule:: optimizely.optimizely_config + :members: diff --git a/docs/source/readme.rst b/docs/source/readme.rst new file mode 100644 index 00000000..57de8658 --- /dev/null +++ b/docs/source/readme.rst @@ -0,0 +1 @@ +.. mdinclude:: ../../README.md \ No newline at end of file diff --git a/requirements/docs.txt b/requirements/docs.txt new file mode 100644 index 00000000..4e4893d1 --- /dev/null +++ b/requirements/docs.txt @@ -0,0 +1,3 @@ +sphinx==2.4.4 +sphinx-rtd-theme==0.4.3 +m2r==0.2.1 \ No newline at end of file diff --git a/setup.py b/setup.py index 1a17451d..d1123a35 100644 --- a/setup.py +++ b/setup.py @@ -51,7 +51,7 @@ 'Programming Language :: Python :: 3.5', 'Programming Language :: Python :: 3.6', ], - packages=find_packages(exclude=['tests']), + packages=find_packages(exclude=['docs', 'tests']), extras_require={'test': TEST_REQUIREMENTS}, install_requires=REQUIREMENTS, tests_require=TEST_REQUIREMENTS,