diff --git a/.gitignore b/.gitignore index ec36322..d3e2429 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,4 @@ node_modules flatisfy/web/static/assets data/ package-lock.json +doc/_build diff --git a/doc/2.docker.md b/doc/2.docker.md index 96b2bad..996ebd5 100644 --- a/doc/2.docker.md +++ b/doc/2.docker.md @@ -1,5 +1,5 @@ -Testing Flatisfy using Docker -============================= +Installing Flatisfy using Docker +================================ A basic `Dockerfile` is available for rapid testing. It is still really hacky and should not be used in production. diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..7c60a13 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,225 @@ +# 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) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: 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 " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @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 " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +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." + +.PHONY: qthelp +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/Flatisfy.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Flatisfy.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Flatisfy" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Flatisfy" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: latex +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)." + +.PHONY: latexpdf +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." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +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." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..3213961 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,343 @@ +# -*- coding: utf-8 -*- +# +# Flatisfy documentation build configuration file, created by +# sphinx-quickstart on Tue Dec 5 14:21:46 2017. +# +# 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. + +# 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('..')) + +# -- 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', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +source_suffix = ['.rst', '.md'] +source_parsers = { + '.md': 'recommonmark.parser.CommonMarkParser', +} + +# The encoding of source files. +# +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Flatisfy' +copyright = u'2017, Phyks (Lucas Verney)' +author = u'Phyks (Lucas Verney)' + +# 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. +# +# The short X.Y version. +version = u'0.1' +# The full version, including alpha/beta/rc tags. +release = u'0.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +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. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# 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 = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- 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 = 'classic' + +# 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. +# " v documentation" by default. +# +# html_title = u'Flatisfy v0.1' + +# A shorter title for the navigation bar. Default is the same as html_title. +# +# html_short_title = None + +# 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 (relative to this directory) to use as a 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'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# +# html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# +# html_last_updated_fmt = None + +# 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 + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' +# +# html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# +# html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Flatisfydoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'Flatisfy.tex', u'Flatisfy Documentation', + u'Phyks (Lucas Verney)', '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 + +# Documents to append as an appendix to all manuals. +# +# latex_appendices = [] + +# It false, will not define \strong, \code, itleref, \crossref ... but only +# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added +# packages. +# +# latex_keep_old_macro_names = True + +# 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 = [ + (master_doc, 'flatisfy', u'Flatisfy Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +# +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Flatisfy', u'Flatisfy Documentation', + author, 'Flatisfy', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +# +# texinfo_appendices = [] + +# If false, no module index is generated. +# +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# +# texinfo_no_detailmenu = False diff --git a/doc/flatisfy.data_files.rst b/doc/flatisfy.data_files.rst new file mode 100644 index 0000000..3440d2e --- /dev/null +++ b/doc/flatisfy.data_files.rst @@ -0,0 +1,10 @@ +flatisfy.data_files package +=========================== + +Module contents +--------------- + +.. automodule:: flatisfy.data_files + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/flatisfy.database.rst b/doc/flatisfy.database.rst new file mode 100644 index 0000000..97de934 --- /dev/null +++ b/doc/flatisfy.database.rst @@ -0,0 +1,38 @@ +flatisfy.database package +========================= + +Submodules +---------- + +flatisfy.database.base module +----------------------------- + +.. automodule:: flatisfy.database.base + :members: + :undoc-members: + :show-inheritance: + +flatisfy.database.types module +------------------------------ + +.. automodule:: flatisfy.database.types + :members: + :undoc-members: + :show-inheritance: + +flatisfy.database.whooshalchemy module +-------------------------------------- + +.. automodule:: flatisfy.database.whooshalchemy + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: flatisfy.database + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/flatisfy.filters.rst b/doc/flatisfy.filters.rst new file mode 100644 index 0000000..2bb35c6 --- /dev/null +++ b/doc/flatisfy.filters.rst @@ -0,0 +1,38 @@ +flatisfy.filters package +======================== + +Submodules +---------- + +flatisfy.filters.cache module +----------------------------- + +.. automodule:: flatisfy.filters.cache + :members: + :undoc-members: + :show-inheritance: + +flatisfy.filters.duplicates module +---------------------------------- + +.. automodule:: flatisfy.filters.duplicates + :members: + :undoc-members: + :show-inheritance: + +flatisfy.filters.metadata module +-------------------------------- + +.. automodule:: flatisfy.filters.metadata + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: flatisfy.filters + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/flatisfy.models.rst b/doc/flatisfy.models.rst new file mode 100644 index 0000000..7ef1b3c --- /dev/null +++ b/doc/flatisfy.models.rst @@ -0,0 +1,38 @@ +flatisfy.models package +======================= + +Submodules +---------- + +flatisfy.models.flat module +--------------------------- + +.. automodule:: flatisfy.models.flat + :members: + :undoc-members: + :show-inheritance: + +flatisfy.models.postal_code module +---------------------------------- + +.. automodule:: flatisfy.models.postal_code + :members: + :undoc-members: + :show-inheritance: + +flatisfy.models.public_transport module +--------------------------------------- + +.. automodule:: flatisfy.models.public_transport + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: flatisfy.models + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/flatisfy.rst b/doc/flatisfy.rst new file mode 100644 index 0000000..88821ae --- /dev/null +++ b/doc/flatisfy.rst @@ -0,0 +1,89 @@ +flatisfy package +================ + +Subpackages +----------- + +.. toctree:: + + flatisfy.data_files + flatisfy.database + flatisfy.filters + flatisfy.models + flatisfy.web + +Submodules +---------- + +flatisfy.cmds module +-------------------- + +.. automodule:: flatisfy.cmds + :members: + :undoc-members: + :show-inheritance: + +flatisfy.config module +---------------------- + +.. automodule:: flatisfy.config + :members: + :undoc-members: + :show-inheritance: + +flatisfy.constants module +------------------------- + +.. automodule:: flatisfy.constants + :members: + :undoc-members: + :show-inheritance: + +flatisfy.data module +-------------------- + +.. automodule:: flatisfy.data + :members: + :undoc-members: + :show-inheritance: + +flatisfy.email module +--------------------- + +.. automodule:: flatisfy.email + :members: + :undoc-members: + :show-inheritance: + +flatisfy.exceptions module +-------------------------- + +.. automodule:: flatisfy.exceptions + :members: + :undoc-members: + :show-inheritance: + +flatisfy.fetch module +--------------------- + +.. automodule:: flatisfy.fetch + :members: + :undoc-members: + :show-inheritance: + +flatisfy.tools module +--------------------- + +.. automodule:: flatisfy.tools + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: flatisfy + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/flatisfy.web.routes.rst b/doc/flatisfy.web.routes.rst new file mode 100644 index 0000000..e8445cd --- /dev/null +++ b/doc/flatisfy.web.routes.rst @@ -0,0 +1,22 @@ +flatisfy.web.routes package +=========================== + +Submodules +---------- + +flatisfy.web.routes.api module +------------------------------ + +.. automodule:: flatisfy.web.routes.api + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: flatisfy.web.routes + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/flatisfy.web.rst b/doc/flatisfy.web.rst new file mode 100644 index 0000000..d6cfa43 --- /dev/null +++ b/doc/flatisfy.web.rst @@ -0,0 +1,45 @@ +flatisfy.web package +==================== + +Subpackages +----------- + +.. toctree:: + + flatisfy.web.routes + +Submodules +---------- + +flatisfy.web.app module +----------------------- + +.. automodule:: flatisfy.web.app + :members: + :undoc-members: + :show-inheritance: + +flatisfy.web.configplugin module +-------------------------------- + +.. automodule:: flatisfy.web.configplugin + :members: + :undoc-members: + :show-inheritance: + +flatisfy.web.dbplugin module +---------------------------- + +.. automodule:: flatisfy.web.dbplugin + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: flatisfy.web + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..4a52d31 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,25 @@ +.. Flatisfy documentation master file, created by + sphinx-quickstart on Tue Dec 5 14:21:46 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Flatisfy's documentation! +==================================== + +.. automodule:: flatisfy + +.. toctree:: + + 0.getting_started.md + 1.production.md + 2.docker.md + modules.rst + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/modules.rst b/doc/modules.rst new file mode 100644 index 0000000..bd3dfe5 --- /dev/null +++ b/doc/modules.rst @@ -0,0 +1,7 @@ +Flatisfy +======== + +.. toctree:: + :maxdepth: 4 + + flatisfy diff --git a/flatisfy/cmds.py b/flatisfy/cmds.py index eae3971..8c0e9c0 100644 --- a/flatisfy/cmds.py +++ b/flatisfy/cmds.py @@ -28,9 +28,9 @@ def filter_flats_list(config, constraint_name, flats_list, fetch_details=True): :param config: A config dict. :param constraint_name: The constraint name that the ``flats_list`` should - satisfy. + satisfy. :param fetch_details: Whether additional details should be fetched between - the two passes. + the two passes. :param flats_list: The initial list of flat objects to filter. :return: A dict mapping flat status and list of flat objects. """ @@ -107,11 +107,11 @@ def filter_fetched_flats(config, fetched_flats, fetch_details=True): :param config: A config dict. :param fetch_details: Whether additional details should be fetched between - the two passes. + the two passes. :param fetched_flats: The initial dict mapping constraints to the list of - fetched flat objects to filter. + fetched flat objects to filter. :return: A dict mapping constraints to a dict mapping flat status and list - of flat objects. + of flat objects. """ for constraint_name, flats_list in fetched_flats.items(): fetched_flats[constraint_name] = filter_flats_list( @@ -130,7 +130,7 @@ def import_and_filter(config, load_from_db=False): :param config: A config dict. :param load_from_db: Whether to load flats from database or fetch them - using Weboob. + using Weboob. :return: ``None``. """ # Fetch and filter flats list diff --git a/flatisfy/config.py b/flatisfy/config.py index 4e1d798..268b0b6 100644 --- a/flatisfy/config.py +++ b/flatisfy/config.py @@ -89,7 +89,7 @@ def validate_config(config, check_with_data): :param config: A config dictionary to fetch. :param check_with_data: Whether we should use the available OpenData to - check the config values. + check the config values. :return: ``True`` if the configuration is valid, ``False`` otherwise. """ def _check_constraints_bounds(bounds): @@ -206,7 +206,7 @@ def load_config(args=None, check_with_data=True): :param args: An argparse args structure. :param check_with_data: Whether we should use the available OpenData to - check the config values. Defaults to ``True``. + check the config values. Defaults to ``True``. :return: The loaded config dict. """ LOGGER.info("Initializing configuration...") diff --git a/flatisfy/database/__init__.py b/flatisfy/database/__init__.py index f627717..d6780fd 100644 --- a/flatisfy/database/__init__.py +++ b/flatisfy/database/__init__.py @@ -35,7 +35,7 @@ def init_db(database_uri=None, search_db_uri=None): Initialize the database, ensuring tables exist etc. :param database_uri: An URI describing an engine to use. Defaults to - in-memory SQLite database. + in-memory SQLite database. :param search_db_uri: Path to the Whoosh index file to use. :return: A tuple of an SQLAlchemy session maker and the created engine. """ diff --git a/flatisfy/database/types.py b/flatisfy/database/types.py index ea2afdc..ef048d1 100644 --- a/flatisfy/database/types.py +++ b/flatisfy/database/types.py @@ -16,11 +16,14 @@ class StringyJSON(types.TypeDecorator): From https://avacariu.me/articles/2016/compiling-json-as-text-for-sqlite-with-sqlalchemy. - .. note :: The associated field is immutable. That is, changes to the data - (typically, changing the value of a dict field) will not trigger an update - on the SQL side upon ``commit`` as the reference to the object will not - have been updated. One should force the update by forcing an update of the - reference (by performing a ``copy`` operation on the dict for instance). + .. note :: + + The associated field is immutable. That is, changes to the data + (typically, changing the value of a dict field) will not trigger an + update on the SQL side upon ``commit`` as the reference to the object + will not have been updated. One should force the update by forcing an + update of the reference (by performing a ``copy`` operation on the dict + for instance). """ impl = types.TEXT diff --git a/flatisfy/fetch.py b/flatisfy/fetch.py index 3059055..9a99210 100644 --- a/flatisfy/fetch.py +++ b/flatisfy/fetch.py @@ -98,9 +98,9 @@ class WeboobProxy(object): cities, to comply with housing websites limitations. :param constraints_dict: A dictionary of constraints, as defined in the - config. + config. :return: A list of Weboob ``weboob.capabilities.housing.Query`` - objects. Returns ``None`` if an error occurred. + objects. Returns ``None`` if an error occurred. """ queries = [] @@ -180,7 +180,7 @@ class WeboobProxy(object): :param query: A Weboob `weboob.capabilities.housing.Query`` object. :param max_entries: Maximum number of entries to fetch. :param store_personal_data: Whether personal data should be fetched - from housing posts (phone number etc). + from housing posts (phone number etc). :return: The matching housing posts, dumped as a list of JSON objects. """ housings = [] @@ -206,9 +206,9 @@ class WeboobProxy(object): Get information (details) about an housing post. :param full_flat_id: A Weboob housing post id, in complete form - (ID@BACKEND) + (ID@BACKEND) :param store_personal_data: Whether personal data should be fetched - from housing posts (phone number etc). + from housing posts (phone number etc). :return: The details in JSON. """ flat_id, backend_name = full_flat_id.rsplit("@", 1) @@ -247,7 +247,7 @@ def fetch_flats(config): :param config: A config dict. :return: A dict mapping constraint in config to all available matching - flats. + flats. """ fetched_flats = {} @@ -296,9 +296,10 @@ def load_flats_from_file(json_file, config): :param json_file: The file to load housings list from. :return: A dict mapping constraint in config to all available matching - flats. + flats. .. note:: + As we do not know which constraint is met by a given flat, all the flats are returned for any available constraint, and they will be filtered out afterwards. @@ -323,7 +324,7 @@ def load_flats_from_db(config): :param config: A config dict. :return: A dict mapping constraint in config to all available matching - flats. + flats. """ get_session = database.init_db(config["database"], config["search_index"]) diff --git a/flatisfy/filters/__init__.py b/flatisfy/filters/__init__.py index 01d286b..c4ffd33 100644 --- a/flatisfy/filters/__init__.py +++ b/flatisfy/filters/__init__.py @@ -86,9 +86,11 @@ def refine_with_details_criteria(flats_list, constraint): details to be fetched. These include minimum number of photos and terms that should appear in description. - .. note :: This has to be done in a separate function and not with the - other criterias as photos and full description are only fetched in the - second pass. + .. note :: + + This has to be done in a separate function and not with the other + criterias as photos and full description are only fetched in the second + pass. :param flats_list: A list of flats dict to filter. :param constraint: The constraint that the ``flats_list`` should satisfy. diff --git a/flatisfy/filters/duplicates.py b/flatisfy/filters/duplicates.py index 28c94d3..0b9ee4a 100644 --- a/flatisfy/filters/duplicates.py +++ b/flatisfy/filters/duplicates.py @@ -56,9 +56,9 @@ def find_number_common_photos(photo_cache, flat1_photos, flat2_photos): Fetch the photos and compare them with dHash method. :param flat1_photos: First list of flat photos. Each photo should be a - ``dict`` with a ``url`` key. + ``dict`` with a ``url`` key. :param flat2_photos: First list of flat photos. Each photo should be a - ``dict`` with a ``url`` key. + ``dict`` with a ``url`` key. :return: The found number of common photos. """ n_common_photos = 0 @@ -93,16 +93,16 @@ def detect(flats_list, key="id", merge=True, should_intersect=False): :param flats_list: A list of flats dicts. :param key: The flat dicts key on which the duplicate detection should be - done. + done. :param merge: Whether the found duplicates should be merged or we should - only keep one of them. + only keep one of them. :param should_intersect: Set to ``True`` if the values in the flat dicts - are lists and you want to deduplicate on non-empty intersection (typically - if they have a common url). + are lists and you want to deduplicate on non-empty intersection + (typically if they have a common url). :return: A tuple of the deduplicated list of flat dicts and the list of all - the flats objects that should be removed and considered as duplicates (they - were already merged). + the flats objects that should be removed and considered as duplicates + (they were already merged). """ # ``seen`` is a dict mapping aggregating the flats by the deduplication # keys. We basically make buckets of flats for every key value. Flats in @@ -173,8 +173,8 @@ def deep_detect(flats_list): :param flats_list: A list of flats dicts. :return: A tuple of the deduplicated list of flat dicts and the list of all - the flats objects that should be removed and considered as duplicates (they - were already merged). + the flats objects that should be removed and considered as duplicates + (they were already merged). """ photo_cache = ImageCache() diff --git a/flatisfy/filters/metadata.py b/flatisfy/filters/metadata.py index 9aa67e4..55ad3e3 100644 --- a/flatisfy/filters/metadata.py +++ b/flatisfy/filters/metadata.py @@ -59,20 +59,20 @@ def fuzzy_match(query, choices, limit=3, threshold=75): :return: Tuples of matching items and associated confidence. - .. note :: This function works by removing any fancy character from the - ``query`` and ``choices`` strings (replacing any non alphabetic and non - numeric characters by space), converting to lower case and normalizing them - (collapsing multiple spaces etc). It also converts any roman numerals to - decimal system. It then compares the string and look for the longest string - in ``choices`` which is a substring of ``query``. The longest one gets a - confidence of 100. The shorter ones get a confidence proportional to their - length. + .. note :: + + This function works by removing any fancy character from the ``query`` + and ``choices`` strings (replacing any non alphabetic and non numeric + characters by space), converting to lower case and normalizing them + (collapsing multiple spaces etc). It also converts any roman numerals + to decimal system. It then compares the string and look for the longest + string in ``choices`` which is a substring of ``query``. The longest + one gets a confidence of 100. The shorter ones get a confidence + proportional to their length. .. seealso :: flatisfy.tools.normalize_string - .. todo :: Is there a better confidence measure? - - :Example: + Example:: >>> match("Paris 14ème", ["Ris", "ris", "Paris 14"], limit=1) [("Paris 14", 100) @@ -85,6 +85,7 @@ def fuzzy_match(query, choices, limit=3, threshold=75): ) [('denfert rochereau', 100), ('saint-jacques', 76)] """ + # TODO: Is there a better confidence measure? normalized_query = tools.normalize_string(query) normalized_choices = [tools.normalize_string(choice) for choice in choices] @@ -130,8 +131,9 @@ def guess_postal_code(flats_list, constraint, config, distance_threshold=20000): :param constraint: The constraint that the ``flats_list`` should satisfy. :param config: A config dict. :param distance_threshold: Maximum distance in meters between the - constraint postal codes (from config) and the one found by this function, - to avoid bad fuzzy matching. Can be ``None`` to disable thresholding. + constraint postal codes (from config) and the one found by this + function, to avoid bad fuzzy matching. Can be ``None`` to disable + thresholding. :return: An updated list of flats dict with guessed postal code. """ @@ -246,7 +248,7 @@ def guess_stations(flats_list, constraint, config, distance_threshold=1500): :param constraint: The constraint that the ``flats_list`` should satisfy. :param config: A config dict. :param distance_threshold: Maximum distance (in meters) between the center - of the postal code and the station to consider it ok. + of the postal code and the station to consider it ok. :return: An updated list of flats dict with guessed nearby stations. """ diff --git a/flatisfy/tools.py b/flatisfy/tools.py index 8de5df9..0521d17 100644 --- a/flatisfy/tools.py +++ b/flatisfy/tools.py @@ -112,11 +112,13 @@ def is_within_interval(value, min_value=None, max_value=None): :param min_value: The lower bound. :param max_value: The upper bound. :return: ``True`` if the value is ``None``. ``True`` or ``False`` whether - the value is within the given interval or not. + the value is within the given interval or not. - .. note:: A value is always within a ``None`` bound. + .. note:: - :Example: + A value is always within a ``None`` bound. + + Example:: >>> is_within_interval(None) True @@ -147,13 +149,12 @@ def normalize_string(string): """ Normalize the given string for matching. - .. todo :: Convert romanian numerals to decimal - :Example: >>> normalize_string("tétéà 14ème-XIV, foobar") 'tetea 14eme xiv, foobar' """ + # TODO: Convert romanian numerals to decimal # ASCIIfy the string string = unidecode.unidecode(string) @@ -267,13 +268,15 @@ def get_travel_time_between(latlng_from, latlng_to, config): by their latitude and longitude. :param latlng_from: A tuple of (latitude, longitude) for the starting - point. + point. :param latlng_to: A tuple of (latitude, longitude) for the destination. :return: A dict of the travel time in seconds and sections of the journey - with GeoJSON paths. Returns ``None`` if it could not fetch it. + with GeoJSON paths. Returns ``None`` if it could not fetch it. - .. note :: Uses the Navitia API. Requires a ``navitia_api_key`` field to be - filled-in in the ``config``. + .. note :: + + Uses the Navitia API. Requires a ``navitia_api_key`` field to be + filled-in in the ``config``. """ travel_time = None diff --git a/flatisfy/web/routes/api.py b/flatisfy/web/routes/api.py index 8d9a45a..6a39ffb 100644 --- a/flatisfy/web/routes/api.py +++ b/flatisfy/web/routes/api.py @@ -19,6 +19,14 @@ from flatisfy.models.postal_code import PostalCode def JSONError(error_code, error_str): + """ + Return an HTTP error with a JSON payload. + + :param error_code: HTTP error code to return. + :param error_str: Error as a string. + :returns: Set correct response parameters and returns JSON-serialized error + content. + """ bottle.response.status = error_code bottle.response.content_type = "application/json" return json.dumps(dict(error=error_str, status_code=error_code)) @@ -63,7 +71,9 @@ def _serialize_flat(flat, config): def index_v1(): """ - API v1 index route: + API v1 index route. + + Example:: GET /api/v1/ """ @@ -78,12 +88,16 @@ def index_v1(): def flats_v1(config, db): """ - API v1 flats route: + API v1 flats route. + + Example:: GET /api/v1/flats - .. note:: Filtering can be done through the ``filter`` GET param, according - to JSON API spec (http://jsonapi.org/recommendations/#filtering). + .. note:: + + Filtering can be done through the ``filter`` GET param, according + to JSON API spec (http://jsonapi.org/recommendations/#filtering). :return: The available flats objects in a JSON ``data`` dict. """ @@ -116,7 +130,9 @@ def flats_v1(config, db): def flat_v1(flat_id, config, db): """ - API v1 flat route: + API v1 flat route. + + Example:: GET /api/v1/flats/:flat_id @@ -137,7 +153,9 @@ def flat_v1(flat_id, config, db): def update_flat_v1(flat_id, config, db): """ - API v1 route to update flat status: + API v1 route to update flat status. + + Example:: PATCH /api/v1/flat/:flat_id Data: { @@ -145,8 +163,10 @@ def update_flat_v1(flat_id, config, db): "visit_date": "ISO8601 DATETIME" } - .. note:: The keys in the data sent are same keys as in ``Flat`` model. You - can provide any subset of them to update part of the flat infos. + .. note:: + + The keys in the data sent are same keys as in ``Flat`` model. You + can provide any subset of them to update part of the flat infos. :return: The new flat object in a JSON ``data`` dict. """ @@ -176,10 +196,12 @@ def time_to_places_v1(config): """ API v1 route to fetch the details of the places to compute time to. + Example:: + GET /api/v1/time_to_places :return: The JSON dump of the places to compute time to (dict of places - names mapped to GPS coordinates). + names mapped to GPS coordinates). """ try: places = {} @@ -199,6 +221,8 @@ def search_v1(db, config): """ API v1 route to perform a fulltext search on flats. + Example:: + POST /api/v1/search Data: { "query": "SOME_QUERY" @@ -227,7 +251,9 @@ def search_v1(db, config): def ics_feed_v1(config, db): """ - API v1 ICS feed of visits route: + API v1 ICS feed of visits route. + + Example:: GET /api/v1/ics/visits.ics