Merge pull request pallets-eco#718 from pallets/docs

use pallets-sphinx-themes

Author: davidism

CHANGES.rst

@@ -6,8 +6,8 @@ Unreleased
 -   Make engine configuration more flexible. (:pr:`684`)
 -   Address SQLAlchemy 1.3 deprecations. (:pr:`684`)
 -   ``get_or_404()`` and ``first_or_404()`` now accept a ``description``
-    parameter to control the 404 message. (:pr:`636`)
--   Use ``time.perf_counter`` for Python 3 on Windows. (:pr:`638`)
+    parameter to control the 404 message. (:issue:`636`)
+-   Use ``time.perf_counter`` for Python 3 on Windows. (:issue:`638`)
 -   Drop support for Python 2.6 and 3.3. (:pr:`687`)
 
 
@@ -27,15 +27,15 @@ Released 2017-10-05
 
 -   If a model has a table name that matches an existing table in the
     metadata, use that table. Fixes a regression where reflected tables
-    were not picked up by models. (:pr:`551`)
+    were not picked up by models. (:issue:`551`)
 -   Raise the correct error when a model has a table name but no primary
     key. (:pr:`556`)
 -   Fix ``repr`` on models that don't have an identity because they have
-    not been flushed yet. (:pr:`555`)
+    not been flushed yet. (:issue:`555`)
 -   Allow specifying a ``max_per_page`` limit for pagination, to avoid
     users specifying high values in the request args. (:pr:`542`)
 -   For ``paginate`` with ``error_out=False``, the minimum value for
-    ``page`` is 1 and ``per_page`` is 0. (:pr:`558`)
+    ``page`` is 1 and ``per_page`` is 0. (:issue:`558`)
 
 
 Version 2.3.0
@@ -51,14 +51,14 @@ Released 2017-09-28
 -   Passing an existing ``declarative_base()`` as ``model_class`` to
     ``SQLAlchemy.__init__`` will use this as the base class instead of
     creating one. This allows customizing the metaclass used to
-    construct the base. (:pr:`546`)
+    construct the base. (:issue:`546`)
 -   The undocumented ``DeclarativeMeta`` internals that the extension
     uses for binds and table name generation have been refactored to
     work as mixins. Documentation is added about how to create a custom
-    metaclass that does not do table name generation. (:pr:`546`)
+    metaclass that does not do table name generation. (:issue:`546`)
 -   Model and metaclass code has been moved to a new ``models`` module.
     ``_BoundDeclarativeMeta`` is renamed to ``DefaultMeta``; the old
-    name will be removed in 3.0. (:pr:`546`)
+    name will be removed in 3.0. (:issue:`546`)
 -   Models have a default ``repr`` that shows the model name and primary
     key. (:pr:`530`)
 -   Fixed a bug where using ``init_app`` would cause connectors to
@@ -79,13 +79,13 @@ Released 2017-02-27, codename Dubnium
 -   Allow listening to SQLAlchemy events on ``db.session``.
     (:pr:`364`)
 -   Allow ``__bind_key__`` on abstract models. (:pr:`373`)
--   Allow ``SQLALCHEMY_ECHO`` to be a string. (:pr:`409`)
+-   Allow ``SQLALCHEMY_ECHO`` to be a string. (:issue:`409`)
 -   Warn when ``SQLALCHEMY_DATABASE_URI`` is not set. (:pr:`443`)
--   Don't let pagination generate invalid page numbers. (:pr:`460`)
+-   Don't let pagination generate invalid page numbers. (:issue:`460`)
 -   Drop support of Flask < 0.10. This means the db session is always
-    tied to the app context and its teardown event. (:pr:`461`)
+    tied to the app context and its teardown event. (:issue:`461`)
 -   Tablename generation logic no longer accesses class properties
-    unless they are ``declared_attr``. (:pr:`467`)
+    unless they are ``declared_attr``. (:issue:`467`)
 
 
 Version 2.1

docs/Makefile

@@ -1,130 +1,19 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-PAPER         =
+SOURCEDIR     = .
 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
-
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> 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."
-
-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/Flask-SQLAlchemy.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Flask-SQLAlchemy.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/Flask-SQLAlchemy"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Flask-SQLAlchemy"
-	@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."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-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: help Makefile
 
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
+# 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)

docs/_templates/sidebarintro.html

@@ -1 +1,4 @@
+Changes
+=======
+
 .. include:: ../CHANGES.rst