From e15695adbafabde6541aa767663fa42954d4bb36 Mon Sep 17 00:00:00 2001 From: Polina Nguen Date: Thu, 26 Mar 2020 18:12:50 -0700 Subject: [PATCH 1/3] Create script to generate html docs with sphinx Add minor changes to README.md and CONTRIBUTING.md for proper conversion to .rst --- .gitignore | 3 ++ CONTRIBUTING.md | 4 +-- README.md | 16 +++++----- docs/Makefile | 20 ++++++++++++ docs/make.bat | 35 +++++++++++++++++++++ docs/source/conf.py | 59 ++++++++++++++++++++++++++++++++++++ docs/source/contributing.rst | 1 + docs/source/index.rst | 13 ++++++++ 8 files changed, 140 insertions(+), 11 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/contributing.rst create mode 100644 docs/source/index.rst diff --git a/.gitignore b/.gitignore index 408a17c4..aa89439b 100644 --- a/.gitignore +++ b/.gitignore @@ -23,3 +23,6 @@ datafile.json # OSX folder metadata *.DS_Store + +# Sphinx documentation +docs/build/ \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ed58d21..9b8aee81 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 diff --git a/README.md b/README.md index 30c0ede4..6192c567 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. @@ -140,7 +136,9 @@ 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. 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/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/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..a898d307 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,59 @@ +# 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('../..')) + +# -- Project information ----------------------------------------------------- + +project = 'Python SDK' +copyright = '2020, Optimizely, Inc' +author = 'Optimizely, Inc.' + +# 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'] \ No newline at end of file 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..df2f5789 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,13 @@ +Python SDK +========== + +.. mdinclude:: ../../README.md + + +.. toctree:: + :caption: Help + + contributing + + + From 79a00d97bdd3754a1c7f7d832e2c26d192712fe2 Mon Sep 17 00:00:00 2001 From: Polina Nguen Date: Fri, 27 Mar 2020 09:09:35 -0700 Subject: [PATCH 2/3] Address comments --- .gitignore | 3 ++- docs/source/conf.py | 2 +- docs/source/index.rst | 5 +---- 3 files changed, 4 insertions(+), 6 deletions(-) diff --git a/.gitignore b/.gitignore index aa89439b..a2ba3089 100644 --- a/.gitignore +++ b/.gitignore @@ -25,4 +25,5 @@ datafile.json *.DS_Store # Sphinx documentation -docs/build/ \ No newline at end of file +docs/build/ + diff --git a/docs/source/conf.py b/docs/source/conf.py index a898d307..9e712490 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -17,7 +17,7 @@ # -- Project information ----------------------------------------------------- project = 'Python SDK' -copyright = '2020, Optimizely, Inc' +copyright = '2016-2020, Optimizely, Inc' author = 'Optimizely, Inc.' # The full version, including alpha/beta/rc tags diff --git a/docs/source/index.rst b/docs/source/index.rst index df2f5789..eb11cab8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,7 +7,4 @@ Python SDK .. toctree:: :caption: Help - contributing - - - + contributing \ No newline at end of file From 005731553bfcbe79a767b7f3d1b2fe4efd10db16 Mon Sep 17 00:00:00 2001 From: Polina Nguen Date: Sat, 28 Mar 2020 20:49:02 -0700 Subject: [PATCH 3/3] Clean up --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index a2ba3089..a0eb93ab 100644 --- a/.gitignore +++ b/.gitignore @@ -26,4 +26,3 @@ datafile.json # Sphinx documentation docs/build/ -