diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index 8cf843c..0000000 --- a/doc/Makefile +++ /dev/null @@ -1,134 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -ziphtml: html - rm -f $(BUILDDIR)/wsme-documentation.zip - cd $(BUILDDIR)/html && zip -r ../wsme-documentation.zip . - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/WebServicesMadeEasy.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/WebServicesMadeEasy.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/WebServicesMadeEasy" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/WebServicesMadeEasy" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/conf.py b/doc/conf.py deleted file mode 100644 index 6f47bcf..0000000 --- a/doc/conf.py +++ /dev/null @@ -1,259 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Web Services Made Easy documentation build configuration file, created by -# sphinx-quickstart on Sun Oct 2 20:27:45 2011. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# 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. -sys.path.insert(0, os.path.abspath('..')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'wsmeext.sphinxext', - 'sphinx.ext.intersphinx'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Web Services Made Easy' -copyright = u'2011, Christophe de Vienne' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -import pkg_resources -wsmedist = pkg_resources.require('WSME')[0] -version = wsmedist.version - -# The short X.Y version. -version = '.'.join(version.split('.')[:2]) -# The full version, including alpha/beta/rc tags. -release = version - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- 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 = 'agogo' -#html_theme_options = { -# "pagewidth": "60em", -# "documentwidth": "40em", -#} - -#html_style = 'wsme.css' - -import cloud_sptheme as csp - -html_theme = 'cloud' -html_theme_path = [csp.get_theme_dir()] - -html_theme_options = { - "roottarget": "index", - "googleanalytics_id": "UA-8510502-6" -} - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -html_title = "WSME %s" % release - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = "WSME" - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# 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'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'WebServicesMadeEasydoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -latex_paper_size = 'a4' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'WebServicesMadeEasy.tex', u'Web Services Made Easy Documentation', - u'Christophe de Vienne', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Additional stuff for the LaTeX preamble. -latex_preamble = ''' -\usepackage[T2A]{fontenc} -\usepackage[utf8]{inputenc} -''' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'webservicesmadeeasy', u'Web Services Made Easy Documentation', - [u'Christophe de Vienne'], 1) -] - - -autodoc_member_order = 'bysource' - -wsme_protocols = [ - 'restjson', 'restxml', -] - -intersphinx_mapping = { - 'python': ('http://docs.python.org/', None), - 'six': ('http://packages.python.org/six/', None), -} - - -def setup(app): - # confval directive taken from the sphinx doc - app.add_object_type('confval', 'confval', - objname='configuration value', - indextemplate='pair: %s; configuration value') diff --git a/doc/gettingstarted.rst b/doc/gettingstarted.rst deleted file mode 100644 index 9d63813..0000000 --- a/doc/gettingstarted.rst +++ /dev/null @@ -1,14 +0,0 @@ -Getting Started -=============== - -For now here is just a working example. -You can find it in the examples directory of the source distribution. - -.. literalinclude:: ../examples/demo/demo.py - :language: python - -When running this example, the following REST client can interrogate -the web services: - -.. literalinclude:: ../examples/demo/client.py - :language: python diff --git a/doc/make.bat b/doc/make.bat deleted file mode 100644 index a88e5fe..0000000 --- a/doc/make.bat +++ /dev/null @@ -1,155 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\WebServicesMadeEasy.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\WebServicesMadeEasy.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -:end diff --git a/doc/requirements.txt b/doc/requirements.txt index 57dd1d9..e78a1bb 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,3 +1,2 @@ -sphinx -cloud_sptheme --r ../requirements.txt +sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD +sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4' # BSD diff --git a/doc/_static/toggle.css b/doc/source/_static/toggle.css similarity index 100% rename from doc/_static/toggle.css rename to doc/source/_static/toggle.css diff --git a/doc/_static/toggle.js b/doc/source/_static/toggle.js similarity index 100% rename from doc/_static/toggle.js rename to doc/source/_static/toggle.js diff --git a/doc/_static/wsme.css b/doc/source/_static/wsme.css similarity index 100% rename from doc/_static/wsme.css rename to doc/source/_static/wsme.css diff --git a/doc/api.rst b/doc/source/api.rst similarity index 100% rename from doc/api.rst rename to doc/source/api.rst diff --git a/doc/changes.rst b/doc/source/changes.rst similarity index 100% rename from doc/changes.rst rename to doc/source/changes.rst diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..8725cba --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,60 @@ +# -*- coding: utf-8 -*- +# +# Web Services Made Easy documentation build configuration file + +# -- 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 = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + 'wsmeext.sphinxext', + 'sphinx.ext.intersphinx', +] + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Web Services Made Easy' +copyright = u'2011, Christophe de Vienne' + +suppress_warnings = ['app.add_directive'] + +# -- 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 = 'default' + +# 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'] + + +# -- Options for sphinx.ext.autodoc extension --------------------------------- + +autodoc_member_order = 'bysource' + + +# -- Options for sphinx.ext.intersphinx extension ----------------------------- + +intersphinx_mapping = { + 'python': ('http://docs.python.org/', None), +} + + +# -- Options for wsme.sphinxext extension ------------------------------------- + +wsme_protocols = [ + 'restjson', 'restxml', +] + + +def setup(app): + # confval directive taken from the sphinx doc + app.add_object_type('confval', 'confval', + objname='configuration value', + indextemplate='pair: %s; configuration value') diff --git a/doc/document.rst b/doc/source/document.rst similarity index 94% rename from doc/document.rst rename to doc/source/document.rst index 8db4924..37f56bc 100644 --- a/doc/document.rst +++ b/doc/source/document.rst @@ -19,8 +19,8 @@ Here we consider that you already quick-started a sphinx project. wsme_protocols = ['restjson', 'restxml'] -#. Copy :download:`toggle.js <_static/toggle.js>` - and :download:`toggle.css <_static/toggle.css>` +#. Copy :download:`toggle.js ` + and :download:`toggle.css ` in your _static directory. The ``wsme`` domain @@ -148,7 +148,7 @@ Full Example Python source ~~~~~~~~~~~~~ -.. literalinclude:: ../wsmeext/sphinxext.py +.. literalinclude:: ../../wsmeext/sphinxext.py :lines: 69-96 :language: python @@ -157,7 +157,7 @@ Documentation source .. code-block:: rst - .. default-domain:: wsmeext + .. default-domain:: wsme .. type:: int @@ -172,7 +172,7 @@ Documentation source Result ~~~~~~ -.. default-domain:: wsmeext +.. default-domain:: wsme .. type:: int diff --git a/doc/functions.rst b/doc/source/functions.rst similarity index 100% rename from doc/functions.rst rename to doc/source/functions.rst diff --git a/doc/source/gettingstarted.rst b/doc/source/gettingstarted.rst new file mode 100644 index 0000000..f240016 --- /dev/null +++ b/doc/source/gettingstarted.rst @@ -0,0 +1,8 @@ +Getting Started +=============== + +For now here is just a working example. +You can find it in the examples directory of the source distribution. + +.. literalinclude:: ../../examples/demo/demo.py + :language: python diff --git a/doc/index.rst b/doc/source/index.rst similarity index 89% rename from doc/index.rst rename to doc/source/index.rst index 7819d57..a033779 100644 --- a/doc/index.rst +++ b/doc/source/index.rst @@ -1,5 +1,5 @@ -.. include:: ../README.rst +.. include:: ../../README.rst Contents -------- diff --git a/doc/integrate.rst b/doc/source/integrate.rst similarity index 98% rename from doc/integrate.rst rename to doc/source/integrate.rst index 843a8a2..fe3bf79 100644 --- a/doc/integrate.rst +++ b/doc/source/integrate.rst @@ -15,8 +15,7 @@ This decorator can have two different names depending on the adapter. take care of calling the adequate decorators of the framework. Generally this decorator is provided for frameworks that use - object-dispatch controllers, such as :ref:`adapter-pecan` and - :ref:`adapter-tg1`. + object-dispatch controllers, such as :ref:`adapter-pecan`. ``@signature`` This decorator only sets the function signature and returns a function diff --git a/doc/protocols.rst b/doc/source/protocols.rst similarity index 98% rename from doc/protocols.rst rename to doc/source/protocols.rst index a3f68d6..e39e225 100644 --- a/doc/protocols.rst +++ b/doc/source/protocols.rst @@ -2,8 +2,7 @@ Protocols ========= In this document the same webservice example will be used to -illustrate the different protocols. Its source code is in the -last chapter (:ref:`protocols-the-example`). +illustrate the different protocols. REST ---- diff --git a/doc/todo.rst b/doc/source/todo.rst similarity index 100% rename from doc/todo.rst rename to doc/source/todo.rst diff --git a/doc/types.rst b/doc/source/types.rst similarity index 73% rename from doc/types.rst rename to doc/source/types.rst index 637a5b7..71432de 100644 --- a/doc/types.rst +++ b/doc/source/types.rst @@ -11,63 +11,64 @@ different protocols map to their own basic types. The native types are : - - .. wsme:type:: bytes - - A pure-ascii string (:py:class:`wsme.types.bytes` which is - :py:class:`str` in Python 2 and :py:class:`bytes` in Python 3). - +- ``.. wsme:type:: bytes`` - - .. wsme:type:: text + A pure-ASCII string (:py:class:`wsme.types.bytes` which is :py:class:`str` in + Python 2 and :py:class:`bytes` in Python 3). - A unicode string (:py:class:`wsme.types.text` which is - :py:class:`unicode` in Python 2 and :py:class:`str` in Python 3). +- ``.. wsme:type:: text`` - - .. wsme:type:: int - - An integer (:py:class:`int`) + A unicode string (:py:class:`wsme.types.text` which is :py:class:`unicode` in + Python 2 and :py:class:`str` in Python 3). - - .. wsme:type:: float - - A float (:py:class:`float`) +- ``.. wsme:type:: int`` - - .. wsme:type:: bool - - A boolean (:py:class:`bool`) + An integer (:py:class:`int`) - - .. wsme:type:: Decimal - - A fixed-width decimal (:py:class:`decimal.Decimal`) +- ``.. wsme:type:: float`` - - .. wsme:type:: date - - A date (:py:class:`datetime.date`) + A float (:py:class:`float`) - - .. wsme:type:: datetime +- ``.. wsme:type:: bool`` - A date and time (:py:class:`datetime.datetime`) + A boolean (:py:class:`bool`) - - .. wsme:type:: time - - A time (:py:class:`datetime.time`) +- ``.. wsme:type:: Decimal`` - - Arrays -- This is a special case. When stating a list - datatype, always state its content type as the unique element - of a list. Example:: + A fixed-width decimal (:py:class:`decimal.Decimal`) - class SomeWebService(object): - @expose([str]) - def getlist(self): - return ['a', 'b', 'c'] +- ``.. wsme:type:: date`` - - Dictionaries -- Statically typed mappings are allowed. When exposing - a dictionary datatype, you can specify the key and value types, - with a restriction on the key value that must be a 'pod' type. - Example:: + A date (:py:class:`datetime.date`) - class SomeType(object): - amap = {str: SomeOthertype} +- ``.. wsme:type:: datetime`` -There are other types that are supported out of the box. See the + A date and time (:py:class:`datetime.datetime`) + +- ``.. wsme:type:: time`` + + A time (:py:class:`datetime.time`) + +- Arrays + + This is a special case. When stating a list datatype, always state its content + type as the unique element of a list. Example:: + + class SomeWebService(object): + @expose([str]) + def getlist(self): + return ['a', 'b', 'c'] + +- Dictionaries + + Statically typed mappings are allowed. When exposing a dictionary datatype, + you can specify the key and value types, with a restriction on the key value + that must be a 'pod' type. Example:: + + class SomeType(object): + amap = {str: SomeOthertype} + +There are other types that are supported out of the box. See the :ref:`pre-defined-user-types`. User types @@ -95,17 +96,17 @@ Pre-defined user types WSME provides some pre-defined user types: -- :class:`binary ` -- for transporting binary data as - base64 strings. -- :class:`Enum ` -- enforce that the values belongs to a - pre-defined list of values. +- :class:`binary ` -- for transporting binary data as base64 + strings. +- :class:`Enum ` -- enforce that the values belongs to a + pre-defined list of values. These types are good examples of how to define user types. Have a look at their source code! Here is a little example that combines :class:`binary ` and :class:`Enum `:: - + ImageKind = Enum(str, 'jpeg', 'gif') class Image(object): @@ -173,7 +174,7 @@ A few things you should know about complex types: Since instances of the type will be created by the protocols when used as input types, they must be instantiable without any argument. - - Complex types are registered automatically + - Complex types are registered automatically (and thus inspected) as soon a they are used in expose or validate, even if they are nested in another complex type. @@ -182,7 +183,7 @@ A few things you should know about complex types: - The datatype attributes will be replaced. - When using the 'short' way of defining attributes, ie setting a + When using the 'short' way of defining attributes, ie setting a simple data type, they will be replaced by a wsattr instance. So, when you write:: diff --git a/tests/test_sphinxext.py b/tests/test_sphinxext.py index 78f80dd..be07ff9 100644 --- a/tests/test_sphinxext.py +++ b/tests/test_sphinxext.py @@ -1,5 +1,5 @@ import unittest -import sphinx +from sphinx.cmd import build import os.path import wsme.types @@ -21,8 +21,8 @@ class TestSphinxExt(unittest.TestCase): if not os.path.exists('.test_sphinxext/'): os.makedirs('.test_sphinxext/') try: - sphinx.main([ - '', + build.main([ +# '', '-b', 'html', '-d', '.test_sphinxext/doctree', docpath, @@ -30,6 +30,7 @@ class TestSphinxExt(unittest.TestCase): ]) assert Exception("Should raise SystemExit 0") except SystemExit as e: + print(e) assert e.code == 0 diff --git a/tox.ini b/tox.ini index f4c4452..163c3fb 100644 --- a/tox.ini +++ b/tox.ini @@ -10,8 +10,8 @@ testtools = basedeps = transaction pecan - cloud_sptheme - Sphinx < 1.2.99 + sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' + sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4' Flask flask-restful @@ -55,15 +55,15 @@ commands = {envbindir}/coverage xml wsme/*.py wsme/rest/*.py wsmeext/*.py {envbindir}/coverage report --show-missing wsme/*.py wsme/protocols/*.py wsmeext/*.py -[testenv:doc] +[testenv:docs] basepython = python3 +whitelist_externals = + rm deps = - cloud_sptheme - Sphinx < 1.2.99 -changedir = - doc + -r doc/requirements.txt commands = - make clean ziphtml + rm -fr doc/build + sphinx-build -W -b html doc/source doc/build/html [testenv:pep8] basepython = python3 diff --git a/wsme/api.py b/wsme/api.py index 67263a0..832625c 100644 --- a/wsme/api.py +++ b/wsme/api.py @@ -80,7 +80,7 @@ class FunctionDefinition(object): #: name of the function argument to pass the host request object. #: Should be set by using the :class:`wsme.types.HostRequest` type - #: in the function @\ :function:`signature` + #: in the function @\ :func:`signature` self.pass_request = False #: Dictionnary of protocol-specific options.