Adding upstream version 3.8.0.upstream/3.8.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

17 files changed, 2615 insertions, 0 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..b3d458c
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,177 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# 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 clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+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 "  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)"
+
+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/Flit.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Flit.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/Flit"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Flit"
+	@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."
+
+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."
+
+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."
+
+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)."
+
+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."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+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."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
diff --git a/doc/_static/flit_logo_nobg.svg b/doc/_static/flit_logo_nobg.svg
new file mode 100644
index 0000000..72a3e7d
--- /dev/null
+++ b/doc/_static/flit_logo_nobg.svg
@@ -0,0 +1,149 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="293.71423"
+   height="293.71423"
+   id="svg3116"
+   version="1.1"
+   inkscape:version="0.48.5 r10040"
+   sodipodi:docname="New document 2">
+  <defs
+     id="defs3118">
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4432"
+       id="linearGradient4452"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(2.0646126,0,0,2.0646126,2131.1883,-505.68517)"
+       x1="294.93112"
+       y1="187.01703"
+       x2="536.55017"
+       y2="453.6973" />
+    <linearGradient
+       inkscape:collect="always"
+       id="linearGradient4432">
+      <stop
+         style="stop-color:#00c48a;stop-opacity:1"
+         offset="0"
+         id="stop4434" />
+      <stop
+         style="stop-color:#00cbff;stop-opacity:1"
+         offset="1"
+         id="stop4436" />
+    </linearGradient>
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4432"
+       id="linearGradient4460"
+       gradientUnits="userSpaceOnUse"
+       x1="3277.5625"
+       y1="604.73828"
+       x2="3786.125"
+       y2="604.73828" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4432"
+       id="linearGradient4454"
+       gradientUnits="userSpaceOnUse"
+       x1="3277.5625"
+       y1="604.73828"
+       x2="3786.125"
+       y2="604.73828" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4432"
+       id="linearGradient4456"
+       gradientUnits="userSpaceOnUse"
+       x1="3277.5625"
+       y1="604.73828"
+       x2="3786.125"
+       y2="604.73828" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4432"
+       id="linearGradient4458"
+       gradientUnits="userSpaceOnUse"
+       x1="3277.5625"
+       y1="604.73828"
+       x2="3786.125"
+       y2="604.73828" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.98994949"
+     inkscape:cx="421.10472"
+     inkscape:cy="117.57302"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0"
+     inkscape:window-width="1680"
+     inkscape:window-height="987"
+     inkscape:window-x="1680"
+     inkscape:window-y="27"
+     inkscape:window-maximized="1" />
+  <metadata
+     id="metadata3121">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-204.57382,-259.79316)">
+    <g
+       transform="matrix(0.24278029,0,0,0.24278029,-425.3047,353.61591)"
+       id="g4440">
+      <path
+         id="path4442"
+         style="fill:url(#linearGradient4452);fill-opacity:1;fill-rule:evenodd;stroke:none"
+         d="m 3027.3295,254.07953 c -13.7048,13.09172 -26.0357,28.06465 -37.0176,44.61328 l 0,41.02539 c 0,5.00744 1.7866,9.29826 5.3633,12.875 3.5768,3.57674 7.8695,5.36524 12.877,5.36524 5.3651,0 9.8353,-1.7885 13.4121,-5.36524 3.5767,-3.57674 5.3652,-7.86756 5.3652,-12.875 l 0,-85.63867 z m 40.2012,-35.61328 -40.2012,0 0,35.61328 c 2.8934,-2.76398 5.8436,-5.45128 8.8594,-8.04492 11.4454,-9.57254 21.8635,-18.67845 31.3418,-27.56836 z m 34.6465,-37.01953 c -9.7805,12.36045 -21.2701,24.47349 -34.6465,37.01953 l 46.7148,0 c 5.0075,0 9.2983,-1.78849 12.875,-5.36524 3.5768,-3.57674 5.3653,-7.86951 5.3653,-12.87695 0,-5.36511 -1.7885,-9.83537 -5.3653,-13.41211 -3.5767,-3.57674 -7.8675,-5.36523 -12.875,-5.36523 l -12.0683,0 z m 33.4824,-60.625 -108.3301,0 0,60.625 74.8477,0 c 14.8892,-18.81683 25.825,-38.22167 33.4824,-60.625 z m 9.5449,-37.019527 c -1.2585,5.3045 -2.516,10.94337 -3.7636,17.044917 -1.6666,6.94336 -3.5949,13.57773 -5.7813,19.97461 l 23.6523,0 c 5.0075,0 9.3003,-1.78849 12.877,-5.36524 3.5767,-3.93441 5.3652,-8.40662 5.3652,-13.41406 0,-5.007437 -1.7885,-9.298257 -5.3652,-12.874997 -3.5767,-3.57674 -7.8695,-5.36523 -12.877,-5.36523 l -14.1074,0 z m -476.3222,-177.33008 c -2.0115,-10e-4 -4.0205,0.0285 -6.0352,0.0957 -32.2353,1.07179 -39.6278,16.38542 -12.3691,36.69141 27.2586,20.30597 67.4768,42.69338 95.8925,62.71679 28.4157,20.02339 35.7846,52.54784 62.5118,70.95899 26.7272,18.41115 54.3969,37.466677 74.8691,57.441407 20.4723,19.97478 42.8139,29.80954 62.9473,12.42382 -41.9066,63.48263 12.2332,134.84987 -173.1446,298.5918 29.2843,16.0722 57.5499,-20.52973 74.8907,-31.10547 2.5476,26.72831 -25.0012,91.1355 -29.2129,135.5625 21.025,-46.6543 56.9285,-120.22794 63.457,-115.36328 9.8881,7.3681 14.1396,135.40743 24.3965,116.33203 21.0116,-25.8867 22.3263,-107.36363 34.0937,-138.89062 11.2667,-42.29933 27.605,-80.7941 49.1328,-113.23438 l 0,-196.65039 c 0,-5.007437 1.7866,-9.298257 5.3633,-12.874997 3.5768,-3.57674 7.8695,-5.36523 12.877,-5.36523 l 136.6523,0 c 15.517,-65.40122 31.2666,-72.74791 32.5215,-83.04883003 13.2678,-9.65059997 122.3748,-33.57495997 180.1094,-40.48437997 -50.3218,-5.57548 -143.4532,11.69044 -195.586,7.36328 -73.7651,-34.78206 -111.4896,10.40375 -121.4531,64.52149 -83.501,33.35098 -204.8488,-83.78957 -259.7637,-101.41602 -51.4826,-16.52477 -81.9782,-24.2477 -112.1503,-24.26562 z m 83.1191,-45.779303 c -0.8667,-0.008 -1.7091,4.6e-4 -2.5293,0.0254 -22.9645,0.69796 -27.5787,14.12698 -6.4688,35.07813 7.5478,7.490993 16.3801,15.378493 25.6504,23.388673 3.4327,1.07931 6.7052,2.08334 10.3399,3.25 54.6631,17.54562 175.142,133.67703 258.6035,101.84765 -64.3681,-33.00238 -126.9043,-104.68293 -163.5801,-122.48828 -48.6408,-23.613873 -77.7408,-35.557113 -107.6094,-39.826173 -1.9912,-0.28458 -3.988,-0.53646 -5.9921,-0.7539 -3.0061,-0.32634 -5.8141,-0.49799 -8.4141,-0.52149 z"
+         inkscape:connector-curvature="0" />
+      <g
+         id="g4444"
+         style="fill:url(#linearGradient4460);fill-opacity:1"
+         transform="translate(-52.527932,-383.85797)">
+        <path
+           id="path4446"
+           d="m 3295.8047,467.66016 c -5.0075,0 -9.3002,1.78849 -12.877,5.36523 -3.5767,3.57674 -5.3652,7.86756 -5.3652,12.875 l 0,237.67578 c 0,5.00744 1.7885,9.29826 5.3652,12.875 3.5768,3.57674 7.8695,5.36524 12.877,5.36524 l 150.7598,0 c 5.0074,0 9.2982,-1.7885 12.875,-5.36524 3.5767,-3.57674 5.3652,-7.86756 5.3652,-12.875 0,-5.36511 -1.7885,-9.83732 -5.3652,-13.41406 -3.5768,-3.57674 -7.8676,-5.36328 -12.875,-5.36328 l -131.9825,0 0,-218.89844 c 0,-5.00744 -1.7885,-9.29826 -5.3652,-12.875 -3.5767,-3.57674 -8.047,-5.36523 -13.4121,-5.36523 z"
+           style="fill:url(#linearGradient4454);fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path4448"
+           d="m 3532.623,467.66016 c -5.0074,0 -9.2982,1.78849 -12.875,5.36523 -3.5767,3.57674 -5.3652,7.86756 -5.3652,12.875 l 0,237.67578 c 0,5.00744 1.7885,9.29826 5.3652,12.875 3.5768,3.57674 7.8676,5.36524 12.875,5.36524 5.3652,0 9.8374,-1.7885 13.4141,-5.36524 3.5768,-3.57674 5.3652,-7.86756 5.3652,-12.875 l 0,-237.67578 c 0,-5.00744 -1.7884,-9.29826 -5.3652,-12.875 -3.5767,-3.57674 -8.0489,-5.36523 -13.4141,-5.36523 z"
+           style="fill:url(#linearGradient4456);fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path4450"
+           d="m 3617.123,467.66016 c -5.0074,0 -9.2982,1.78849 -12.875,5.36523 -3.5767,3.57674 -5.3652,7.86756 -5.3652,12.875 0,5.00744 1.7885,9.47965 5.3652,13.41406 3.5768,3.57675 7.8676,5.36524 12.875,5.36524 l 56.8711,0 0,218.89648 c 0,5.00744 1.7885,9.29826 5.3653,12.875 3.5767,3.57674 7.8695,5.36524 12.8769,5.36524 5.3651,0 9.8354,-1.7885 13.4121,-5.36524 3.5768,-3.57674 5.3653,-7.86756 5.3653,-12.875 l 0,-218.89648 56.8691,0 c 5.0075,0 9.3002,-1.78849 12.877,-5.36524 3.5767,-3.93441 5.3652,-8.40662 5.3652,-13.41406 0,-5.00744 -1.7885,-9.29826 -5.3652,-12.875 -3.5768,-3.57674 -7.8695,-5.36523 -12.877,-5.36523 l -150.7598,0 z"
+           style="fill:url(#linearGradient4458);fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+      </g>
+    </g>
+  </g>
+</svg>
diff --git a/doc/_static/flit_logo_nobg_cropped.png b/doc/_static/flit_logo_nobg_cropped.png
new file mode 100644
index 0000000..5385556
--- /dev/null
+++ b/doc/_static/flit_logo_nobg_cropped.png
diff --git a/doc/_static/flit_logo_nobg_cropped.svg b/doc/_static/flit_logo_nobg_cropped.svg
new file mode 100644
index 0000000..2918743
--- /dev/null
+++ b/doc/_static/flit_logo_nobg_cropped.svg
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="293.54721"
+   height="194.0495"
+   id="svg3116"
+   version="1.1"
+   inkscape:version="0.48.5 r10040"
+   sodipodi:docname="flit_logo_nobg.svg">
+  <defs
+     id="defs3118">
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4432"
+       id="linearGradient4452"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(2.0646126,0,0,2.0646126,2131.1883,-505.68517)"
+       x1="294.93112"
+       y1="187.01703"
+       x2="536.55017"
+       y2="453.6973" />
+    <linearGradient
+       inkscape:collect="always"
+       id="linearGradient4432">
+      <stop
+         style="stop-color:#00c48a;stop-opacity:1"
+         offset="0"
+         id="stop4434" />
+      <stop
+         style="stop-color:#00cbff;stop-opacity:1"
+         offset="1"
+         id="stop4436" />
+    </linearGradient>
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4432"
+       id="linearGradient4460"
+       gradientUnits="userSpaceOnUse"
+       x1="3277.5625"
+       y1="604.73828"
+       x2="3786.125"
+       y2="604.73828" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4432"
+       id="linearGradient4454"
+       gradientUnits="userSpaceOnUse"
+       x1="3277.5625"
+       y1="604.73828"
+       x2="3786.125"
+       y2="604.73828" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4432"
+       id="linearGradient4456"
+       gradientUnits="userSpaceOnUse"
+       x1="3277.5625"
+       y1="604.73828"
+       x2="3786.125"
+       y2="604.73828" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4432"
+       id="linearGradient4458"
+       gradientUnits="userSpaceOnUse"
+       x1="3277.5625"
+       y1="604.73828"
+       x2="3786.125"
+       y2="604.73828" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4432"
+       id="linearGradient3991"
+       gradientUnits="userSpaceOnUse"
+       x1="3277.5625"
+       y1="604.73828"
+       x2="3786.125"
+       y2="604.73828" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.4"
+     inkscape:cx="221.08413"
+     inkscape:cy="35.027636"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0"
+     inkscape:window-width="1680"
+     inkscape:window-height="987"
+     inkscape:window-x="1680"
+     inkscape:window-y="27"
+     inkscape:window-maximized="1" />
+  <metadata
+     id="metadata3121">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-204.65524,-306.77908)">
+    <g
+       transform="matrix(0.24278029,0,0,0.24278029,-425.3047,353.61591)"
+       id="g4440">
+      <path
+         id="path4442"
+         style="fill:url(#linearGradient4452);fill-opacity:1;fill-rule:evenodd;stroke:none"
+         d="m 3027.3295,254.07953 c -13.7048,13.09172 -26.0357,28.06465 -37.0176,44.61328 l 0,41.02539 c 0,5.00744 1.7866,9.29826 5.3633,12.875 3.5768,3.57674 7.8695,5.36524 12.877,5.36524 5.3651,0 9.8353,-1.7885 13.4121,-5.36524 3.5767,-3.57674 5.3652,-7.86756 5.3652,-12.875 l 0,-85.63867 z m 40.2012,-35.61328 -40.2012,0 0,35.61328 c 2.8934,-2.76398 5.8436,-5.45128 8.8594,-8.04492 11.4454,-9.57254 21.8635,-18.67845 31.3418,-27.56836 z m 34.6465,-37.01953 c -9.7805,12.36045 -21.2701,24.47349 -34.6465,37.01953 l 46.7148,0 c 5.0075,0 9.2983,-1.78849 12.875,-5.36524 3.5768,-3.57674 5.3653,-7.86951 5.3653,-12.87695 0,-5.36511 -1.7885,-9.83537 -5.3653,-13.41211 -3.5767,-3.57674 -7.8675,-5.36523 -12.875,-5.36523 l -12.0683,0 z m 33.4824,-60.625 -108.3301,0 0,60.625 74.8477,0 c 14.8892,-18.81683 25.825,-38.22167 33.4824,-60.625 z m 9.5449,-37.019527 c -1.2585,5.3045 -2.516,10.94337 -3.7636,17.044917 -1.6666,6.94336 -3.5949,13.57773 -5.7813,19.97461 l 23.6523,0 c 5.0075,0 9.3003,-1.78849 12.877,-5.36524 3.5767,-3.93441 5.3652,-8.40662 5.3652,-13.41406 0,-5.007437 -1.7885,-9.298257 -5.3652,-12.874997 -3.5767,-3.57674 -7.8695,-5.36523 -12.877,-5.36523 l -14.1074,0 z m -476.3222,-177.33008 c -2.0115,-10e-4 -4.0205,0.0285 -6.0352,0.0957 -32.2353,1.07179 -39.6278,16.38542 -12.3691,36.69141 27.2586,20.30597 67.4768,42.69338 95.8925,62.71679 28.4157,20.02339 35.7846,52.54784 62.5118,70.95899 26.7272,18.41115 54.3969,37.466677 74.8691,57.441407 20.4723,19.97478 42.8139,29.80954 62.9473,12.42382 -41.9066,63.48263 12.2332,134.84987 -173.1446,298.5918 29.2843,16.0722 57.5499,-20.52973 74.8907,-31.10547 2.5476,26.72831 -25.0012,91.1355 -29.2129,135.5625 21.025,-46.6543 56.9285,-120.22794 63.457,-115.36328 9.8881,7.3681 14.1396,135.40743 24.3965,116.33203 21.0116,-25.8867 22.3263,-107.36363 34.0937,-138.89062 11.2667,-42.29933 27.605,-80.7941 49.1328,-113.23438 l 0,-196.65039 c 0,-5.007437 1.7866,-9.298257 5.3633,-12.874997 3.5768,-3.57674 7.8695,-5.36523 12.877,-5.36523 l 136.6523,0 c 15.517,-65.40122 31.2666,-72.74791 32.5215,-83.04883003 13.2678,-9.65059997 122.3748,-33.57495997 180.1094,-40.48437997 -50.3218,-5.57548 -143.4532,11.69044 -195.586,7.36328 -73.7651,-34.78206 -111.4896,10.40375 -121.4531,64.52149 -83.501,33.35098 -204.8488,-83.78957 -259.7637,-101.41602 -51.4826,-16.52477 -81.9782,-24.2477 -112.1503,-24.26562 z m 83.1191,-45.779303 c -0.8667,-0.008 -1.7091,4.6e-4 -2.5293,0.0254 -22.9645,0.69796 -27.5787,14.12698 -6.4688,35.07813 7.5478,7.490993 16.3801,15.378493 25.6504,23.388673 3.4327,1.07931 6.7052,2.08334 10.3399,3.25 54.6631,17.54562 175.142,133.67703 258.6035,101.84765 -64.3681,-33.00238 -126.9043,-104.68293 -163.5801,-122.48828 -48.6408,-23.613873 -77.7408,-35.557113 -107.6094,-39.826173 -1.9912,-0.28458 -3.988,-0.53646 -5.9921,-0.7539 -3.0061,-0.32634 -5.8141,-0.49799 -8.4141,-0.52149 z"
+         inkscape:connector-curvature="0" />
+      <g
+         id="g4444"
+         style="fill:url(#linearGradient3991);fill-opacity:1"
+         transform="translate(-52.527932,-383.85797)">
+        <path
+           id="path4446"
+           d="m 3295.8047,467.66016 c -5.0075,0 -9.3002,1.78849 -12.877,5.36523 -3.5767,3.57674 -5.3652,7.86756 -5.3652,12.875 l 0,237.67578 c 0,5.00744 1.7885,9.29826 5.3652,12.875 3.5768,3.57674 7.8695,5.36524 12.877,5.36524 l 150.7598,0 c 5.0074,0 9.2982,-1.7885 12.875,-5.36524 3.5767,-3.57674 5.3652,-7.86756 5.3652,-12.875 0,-5.36511 -1.7885,-9.83732 -5.3652,-13.41406 -3.5768,-3.57674 -7.8676,-5.36328 -12.875,-5.36328 l -131.9825,0 0,-218.89844 c 0,-5.00744 -1.7885,-9.29826 -5.3652,-12.875 -3.5767,-3.57674 -8.047,-5.36523 -13.4121,-5.36523 z"
+           style="fill:url(#linearGradient4454);fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path4448"
+           d="m 3532.623,467.66016 c -5.0074,0 -9.2982,1.78849 -12.875,5.36523 -3.5767,3.57674 -5.3652,7.86756 -5.3652,12.875 l 0,237.67578 c 0,5.00744 1.7885,9.29826 5.3652,12.875 3.5768,3.57674 7.8676,5.36524 12.875,5.36524 5.3652,0 9.8374,-1.7885 13.4141,-5.36524 3.5768,-3.57674 5.3652,-7.86756 5.3652,-12.875 l 0,-237.67578 c 0,-5.00744 -1.7884,-9.29826 -5.3652,-12.875 -3.5767,-3.57674 -8.0489,-5.36523 -13.4141,-5.36523 z"
+           style="fill:url(#linearGradient4456);fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path4450"
+           d="m 3617.123,467.66016 c -5.0074,0 -9.2982,1.78849 -12.875,5.36523 -3.5767,3.57674 -5.3652,7.86756 -5.3652,12.875 0,5.00744 1.7885,9.47965 5.3652,13.41406 3.5768,3.57675 7.8676,5.36524 12.875,5.36524 l 56.8711,0 0,218.89648 c 0,5.00744 1.7885,9.29826 5.3653,12.875 3.5767,3.57674 7.8695,5.36524 12.8769,5.36524 5.3651,0 9.8354,-1.7885 13.4121,-5.36524 3.5768,-3.57674 5.3653,-7.86756 5.3653,-12.875 l 0,-218.89648 56.8691,0 c 5.0075,0 9.3002,-1.78849 12.877,-5.36524 3.5767,-3.93441 5.3652,-8.40662 5.3652,-13.41406 0,-5.00744 -1.7885,-9.29826 -5.3652,-12.875 -3.5768,-3.57674 -7.8695,-5.36523 -12.877,-5.36523 l -150.7598,0 z"
+           style="fill:url(#linearGradient4458);fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+      </g>
+    </g>
+  </g>
+</svg>
diff --git a/doc/bootstrap.rst b/doc/bootstrap.rst
new file mode 100644
index 0000000..19d7d92
--- /dev/null
+++ b/doc/bootstrap.rst
@@ -0,0 +1,41 @@
+Bootstrapping
+=============
+
+Flit is itself packaged using Flit, as are some foundational packaging tools
+such as ``pep517``. So where can you start if you need to install everything
+from source?
+
+.. note::
+
+   For most users, ``pip`` handles all this automatically. You should only need
+   to deal with this if you're building things entirely from scratch, such as
+   putting Python packages into another package format.
+
+The key piece is ``flit_core``. This is a package which can build itself using
+nothing except Python and the standard library. From an unpacked source archive,
+you can make a wheel by running::
+
+    python -m flit_core.wheel
+
+And then you can install this wheel with the ``bootstrap_install.py`` script
+included in the sdist (or by unzipping it to the correct directory)::
+
+    # Install to site-packages for this Python:
+    python bootstrap_install.py dist/flit_core-*.whl
+
+    # Install somewhere else:
+    python bootstrap_install.py --installdir /path/to/site-packages dist/flit_core-*.whl
+
+As of version 3.6, flit_core bundles the ``tomli`` TOML parser, to avoid a
+dependency cycle. If you need to unbundle it, you will need to special-case
+installing flit_core and/or tomli to get around that cycle.
+
+After ``flit_core``, I recommend that you get `installer
+<https://pypi.org/project/installer/>`_ set up. You can use
+``python -m flit_core.wheel`` again to make a wheel, and then use installer
+itself (from the source directory) to install it.
+
+After that, you probably want to get `build <https://pypi.org/project/build/>`_
+and its dependencies installed as the goal of the bootstrapping phase. You can
+then use ``build`` to create wheels of any other Python packages, and
+``installer`` to install them.
diff --git a/doc/cmdline.rst b/doc/cmdline.rst
new file mode 100644
index 0000000..c443ddd
--- /dev/null
+++ b/doc/cmdline.rst
@@ -0,0 +1,262 @@
+Flit command line interface
+===========================
+
+All operations use the ``flit`` command, followed by one of a number of
+subcommands.
+
+Common options
+--------------
+
+.. program:: flit
+
+.. option:: -f <path>, --ini-file <path>
+
+   Path to a config file specifying the module to build. The default is
+   ``pyproject.toml``.
+
+.. option::  --version
+
+   Show the version of Flit in use.
+
+.. option:: --help
+
+   Show help on the command-line interface.
+
+.. option:: --debug
+
+   Show more detailed logs about what flit is doing.
+
+.. _build_cmd:
+
+``flit build``
+--------------
+
+.. program:: flit build
+
+Build a wheel and an sdist (tarball) from the package.
+
+.. option:: --format <format>
+
+   Limit to building either ``wheel`` or ``sdist``.
+
+.. option:: --setup-py
+
+   Generate a ``setup.py`` file in the sdist, so it can be installed by older
+   versions of pip.
+
+.. option:: --no-setup-py
+
+   Don't generate a setup.py file in the sdist. This is the default.
+   An sdist built without this will only work with tools that support PEP 517,
+   but the wheel will still be usable by any compatible tool.
+
+   .. versionchanged:: 3.5
+
+      Generating ``setup.py`` disabled by default.
+
+.. _publish_cmd:
+
+``flit publish``
+----------------
+
+.. program:: flit publish
+
+Build a wheel and an sdist (tarball) from the package, and upload them to PyPI
+or another repository.
+
+.. option:: --format <format>
+
+   Limit to publishing either ``wheel`` or ``sdist``.
+   You should normally publish the two formats together.
+
+.. option:: --setup-py
+
+   Generate a ``setup.py`` file in the sdist, so it can be installed by older
+   versions of pip.
+
+.. option:: --no-setup-py
+
+   Don't generate a setup.py file in the sdist. This is the default.
+   An sdist built without this will only work with tools that support PEP 517,
+   but the wheel will still be usable by any compatible tool.
+
+   .. versionchanged:: 3.5
+
+      Generating ``setup.py`` disabled by default.
+
+.. option:: --repository <repository>
+
+   Name of a repository to upload packages to. Should match a section in
+   ``~/.pypirc``. The default is ``pypi``.
+
+.. option:: --pypirc <pypirc>
+
+   The .pypirc config file to be used. The default is ``~/.pypirc``.
+
+.. seealso:: :doc:`upload`
+
+.. _install_cmd:
+
+``flit install``
+----------------
+
+.. program:: flit install
+
+Install the package on your system.
+
+By default, the package is installed to the same Python environment that Flit
+itself is installed in; use :option:`--python` or :envvar:`FLIT_INSTALL_PYTHON`
+to override this.
+
+If you don't have permission to modify the environment (e.g. the system Python
+on Linux), Flit may do a user install instead. Use the :option:`--user` or
+:option:`--env` flags to force this one way or the other, rather than letting
+Flit guess.
+
+.. option:: -s, --symlink
+
+   Symlink the module into site-packages rather than copying it, so that you
+   can test changes without reinstalling the module.
+
+.. option:: --pth-file
+
+   Create a ``.pth`` file in site-packages rather than copying the module, so
+   you can test changes without reinstalling. This is a less elegant alternative
+   to ``--symlink``, but it works on Windows, which typically doesn't allow
+   symlinks.
+
+.. option:: --deps <dependency option>
+
+   Which dependencies to install. One of ``all``, ``production``, ``develop``,
+   or ``none``. ``all`` and ``develop`` install the extras ``test``, ``doc``,
+   and ``dev``. Default ``all``.
+
+.. option:: --extras <extra[,extra,...]>
+
+   Which named extra features to install dependencies for. Specify ``all`` to
+   install all optional dependencies, or a comma-separated list of extras.
+   Default depends on ``--deps``.
+
+.. option:: --only-deps
+
+   Install the dependencies of this package, but not the package itself.
+
+   This can be useful for e.g. building a container image, where your own code
+   is copied or mounted into the container at a later stage.
+
+   .. versionadded:: 3.8
+
+.. option:: --user
+
+   Do a user-local installation. This is the default if flit is not in a
+   virtualenv or conda env (if the environment's library directory is
+   read-only and ``site.ENABLE_USER_SITE`` is true).
+
+.. option:: --env
+
+   Install into the environment - the opposite of :option:`--user`.
+   This is the default in a virtualenv or conda env (if the environment's
+   library directory is writable or ``site.ENABLE_USER_SITE`` is false).
+
+.. option:: --python <path to python>
+
+   Install for another Python, identified by the path of the python
+   executable. Using this option, you can install a module for Python 2, for
+   instance. See :envvar:`FLIT_INSTALL_PYTHON` if this option is not given.
+
+   .. versionchanged:: 2.1
+      Added :envvar:`FLIT_INSTALL_PYTHON` and use its value over the Python
+      running Flit when an explicit :option:`--python` option is not given.
+
+.. note::
+
+   Flit calls pip to do the installation. You can set any of pip's options
+   `using its environment variables
+   <https://pip.pypa.io/en/stable/topics/configuration/#environment-variables>`__.
+
+   When you use the :option:`--symlink` or :option:`--pth-file` options, pip
+   is used to install dependencies. Otherwise, Flit builds a wheel and then
+   calls pip to install that.
+
+.. _init_cmd:
+
+``flit init``
+-------------
+
+.. program:: flit init
+
+Create a new ``pyproject.toml``  config file by prompting for information about
+the module in the current directory.
+
+Environment variables
+---------------------
+
+.. envvar:: FLIT_NO_NETWORK
+
+   .. versionadded:: 0.10
+
+   Setting this to any non-empty value will stop flit from making network
+   connections (unless you explicitly ask to upload a package). This
+   is intended for downstream packagers, so if you use this, it's up to you to
+   ensure any necessary dependencies are installed.
+
+.. envvar:: FLIT_ROOT_INSTALL
+
+   By default, ``flit install`` will fail when run as root on POSIX systems,
+   because installing Python modules systemwide is not recommended. Setting
+   this to any non-empty value allows installation as root. It has no effect on
+   Windows.
+
+.. envvar:: FLIT_USERNAME
+            FLIT_PASSWORD
+            FLIT_INDEX_URL
+
+   .. versionadded:: 0.11
+
+   Set a username, password, and index URL for uploading packages.
+   See :ref:`uploading packages with environment variables <upload_envvars>`
+   for more information.
+   
+   Token-based upload to PyPI is supported. To upload using a PyPI token,
+   set ``FLIT_USERNAME`` to ``__token__``, and ``FLIT_PASSWORD`` to the
+   token value.
+
+.. envvar:: FLIT_ALLOW_INVALID
+
+   .. versionadded:: 0.13
+
+   Setting this to any non-empty value tells Flit to continue if it detects
+   invalid metadata, instead of failing with an error. Problems will still be
+   reported in the logs, but won't cause Flit to stop.
+
+   If the metadata is invalid, uploading the package to PyPI may fail. This
+   environment variable provides an escape hatch in case Flit incorrectly
+   rejects your valid metadata. If you need to use it and you believe your
+   metadata is valid, please `open an issue <https://github.com/pypa/flit/issues>`__.
+
+.. envvar:: FLIT_INSTALL_PYTHON
+
+   .. versionadded:: 2.1
+
+   .. program:: flit install
+
+   Set a default Python interpreter for :ref:`install_cmd` to use when
+   :option:`--python` is not specified. The value can be either an absolute
+   path, or a command name (which will be found in ``PATH``). If this is unset
+   or empty, the module is installed for the copy of Python that is running
+   Flit.
+
+.. envvar:: SOURCE_DATE_EPOCH
+
+   To make reproducible builds, set this to a timestamp as a number of seconds
+   since the start of the year 1970 in UTC, and document the value you used.
+   On Unix systems, you can get a value for the current time by running::
+
+       date +%s
+
+
+   .. seealso::
+
+      `The SOURCE_DATE_EPOCH specification
+      <https://reproducible-builds.org/specs/source-date-epoch/>`__
+
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..cce9bee
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,264 @@
+# -*- coding: utf-8 -*-
+#
+# Flit documentation build configuration file, created by
+# sphinx-quickstart on Sun Mar 15 19:16:41 2015.
+#
+# 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
+import 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',
+    'sphinxcontrib_github_alt',
+    'sphinx_rtd_theme',
+]
+
+github_project_url = "https://github.com/pypa/flit"
+
+# 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'Flit'
+copyright = u'2015, Thomas Kluyver'
+
+# 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 = '3.8.0'
+# The full version, including alpha/beta/rc tags.
+release = version #+ '.1'
+
+# 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 = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = 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 = 'sphinx_rtd_theme'
+
+# 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
+# "<project> v<release> documentation".
+#html_title = None
+
+# 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 = '_static/flit_logo_nobg_cropped.svg'
+
+# 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']
+
+# 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 '', 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 <link> 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 = 'Flitdoc'
+
+
+# -- 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': '',
+}
+
+# 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 = [
+  ('index', 'Flit.tex', u'Flit Documentation',
+   u'Thomas Kluyver', '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 = []
+
+# 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', 'flit', u'Flit Documentation',
+     [u'Thomas Kluyver'], 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 = [
+  ('index', 'Flit', u'Flit Documentation',
+   u'Thomas Kluyver', 'Flit', '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/development.rst b/doc/development.rst
new file mode 100644
index 0000000..18090af
--- /dev/null
+++ b/doc/development.rst
@@ -0,0 +1,26 @@
+Developing Flit
+===============
+
+To get a development installation of Flit itself::
+
+    git clone https://github.com/pypa/flit.git
+    cd flit
+    python3 -m pip install docutils requests
+    python3 bootstrap_dev.py
+
+This links Flit into the current Python environment, so you can make changes
+and try them without having to reinstall each time.
+
+Testing
+-------
+
+To run the tests in separate environments for each available Python version::
+
+    tox
+
+`tox <https://tox.readthedocs.io/en/latest/>`_ has many options.
+
+To run the tests in your current environment, run::
+
+    pytest
+
diff --git a/doc/flit_ini.rst b/doc/flit_ini.rst
new file mode 100644
index 0000000..b41d967
--- /dev/null
+++ b/doc/flit_ini.rst
@@ -0,0 +1,113 @@
+:orphan:
+
+The flit.ini config file
+========================
+
+This file lives next to the module or package.
+
+.. note::
+
+   Flit 0.12 and above uses a :doc:`pyproject.toml file <pyproject_toml>` file
+   to store this information. Run ``python3 -m flit.tomlify`` to convert a
+   ``flit.ini`` file to ``pyproject.toml``.
+
+Metadata section
+----------------
+
+There are four required fields:
+
+module
+  The name of the module/package, as you'd use in an import statement.
+author
+  Your name
+author-email
+  Your email address
+home-page
+  A URL for the project, such as its Github repository.
+
+e.g. for flit itself
+
+.. code-block:: ini
+
+    [metadata]
+    module=flit
+    author=Thomas Kluyver
+    author-email=thomas@kluyver.me.uk
+    home-page=https://github.com/pypa/flit
+
+The remaining fields are optional:
+
+requires
+  A list of other packages from PyPI that this package needs. Each package
+  should be on its own line, and may be followed by a version specifier in
+  parentheses, like ``(>=4.1)``, and/or an `environment marker
+  <https://www.python.org/dev/peps/pep-0345/#environment-markers>`_
+  after a semicolon. For example:
+
+  .. code-block:: ini
+
+      requires = requests (>=2.6)
+            configparser; python_version == '2.7'
+
+dev-requires
+  Packages that are required for development. This field is in the same format
+  as ``requires``.
+
+  These are not (yet) encoded in the wheel, but are used when doing
+  ``flit install``.
+description-file
+  A path (relative to the .ini file) to a file containing a longer description
+  of your package to show on PyPI. This should be written in `reStructuredText
+  <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_, if your long
+  description is not valid reStructuredText, a warning will be printed,
+  and it will be interpreted as plain text on PyPI.
+classifiers
+  A list of `Trove classifiers <https://pypi.python.org/pypi?%3Aaction=list_classifiers>`_,
+  one per line, indented.
+requires-python
+  A version specifier for the versions of Python this requires, e.g. ``~=3.3`` or
+  ``>=3.3,<4`` which are equivalents.
+dist-name
+  If you want your package's name on PyPI to be different from the importable
+  module name, set this to the PyPI name.
+keywords
+  Comma separated list of words to help with searching for your package.
+license
+  The name of a license, if you're using one for which there isn't a Trove
+  classifier. It's recommended to use Trove classifiers instead of this in
+  most cases.
+maintainer, maintainer-email
+  Like author, for if you've taken over a project from someone else.
+
+Here's the full example from flit itself:
+
+.. code-block:: ini
+
+    [metadata]
+    author=Thomas Kluyver
+    author-email=thomas@kluyver.me.uk
+    home-page=https://github.com/pypa/flit
+    requires=requests
+    requires-python= >=3
+    description-file=README.rst
+    classifiers=Intended Audience :: Developers
+        License :: OSI Approved :: BSD License
+        Programming Language :: Python :: 3
+        Topic :: Software Development :: Libraries :: Python Modules
+
+.. _flit_ini_scripts:
+
+Scripts section
+---------------
+
+Each key and value in this describes a shell command to be installed along with
+your package. These work like setuptools 'entry points'. Here's the section
+for flit:
+
+.. code-block:: ini
+
+    [scripts]
+    flit = flit:main
+
+This will create a ``flit`` command, which will call the function ``main()``
+imported from :mod:`flit`.
diff --git a/doc/history.rst b/doc/history.rst
new file mode 100644
index 0000000..e04e1fb
--- /dev/null
+++ b/doc/history.rst
@@ -0,0 +1,497 @@
+Release history
+===============
+
+Version 3.8
+-----------
+
+- A project name containing hyphens is now automatically translated to use
+  underscores for the import name (:ghpull:`566`).
+- New option :option:`flit install --only-deps` to install the dependencies of
+  the package, but not the package itself.
+- Add support for recursive globbing (``**``) in sdist includes and excludes
+  (:ghpull:`550`).
+- Python's bytecode cache files (``__pycache__`` folders and ``.pyc`` files)
+  are now always excluded from sdists (:ghpull:`581`).
+- Use tomllib in Python 3.11, rather than tomli (:ghpull:`573`, :ghpull:`604`).
+- Fix crash when unable to get a password from ``keyring`` (:ghpull:`567`).
+- Fix including modified files in sdist when using Mercurial (:ghpull:`541`).
+- Fix for some cases of determining whether a package supports Python 2 or not
+  (:ghpull:`593`).
+- Fix parsing version number from code using multiple assignments (:ghpull:`474`).
+- Document how to use a PyPI token with :envvar:`FLIT_PASSWORD` (:ghpull:`602`).
+- Fix link to information about environment variables for pip (:ghpull:`576`).
+- Link to the docs for the latest stable version in package metadata
+  (:ghpull:`589`).
+- Remove a mention of the ``toml`` package, which is no longer needed, from the
+  :doc:`development` page (:ghpull:`601`).
+- The :doc:`bootstrap <bootstrap>` install script for ``flit_core`` accepts a
+  new ``--install-root`` option.
+- Ensure the license file is included in packages on PyPI (:ghpull:`603`).
+
+Version 3.7.1
+-------------
+
+- Fix building packages which need execution to get the version number,
+  and have a relative import in ``__init__.py`` (:ghpull:`531`).
+
+Version 3.7
+-----------
+
+- Support for :ref:`external data files <pyproject_toml_external_data>` such
+  as man pages or Jupyter extension support files (:ghpull:`510`).
+- Project names are now lowercase in wheel filenames and ``.dist-info`` folder
+  names, in line with the specifications (:ghpull:`498`).
+- Improved support for :doc:`bootstrapping <bootstrap>` a Python environment,
+  e.g. for downstream packagers (:ghpull:`511`). ``flit_core.wheel`` is usable
+  with ``python -m`` to create wheels before the `build <https://pypi.org/project/build/>`_
+  tool is available, and ``flit_core`` sdists also include a script to install
+  itself from a wheel before `installer <https://pypi.org/project/installer/>`_
+  is available.
+- Use newer importlib APIs, fixing some deprecation warnings (:ghpull:`499`).
+
+Version 3.6
+-----------
+
+- ``flit_core`` now bundles the `tomli <https://pypi.org/project/tomli/>`_ TOML
+  parser library (version 1.2.3) to avoid a circular dependency between
+  ``flit_core`` and ``tomli`` (:ghpull:`492`). This means ``flit_core`` now has
+  no dependencies except Python itself, both at build time and at runtime,
+  simplifying :doc:`bootstrapping <bootstrap>`.
+
+Version 3.5.1
+-------------
+
+- Fix development installs with ``flit install --symlink`` and ``--pth-file``,
+  which were broken in 3.5.0, especially for packages using a ``src`` folder
+  (:ghpull:`472`).
+
+Version 3.5
+-----------
+
+- You can now use Flit to distribute a module or package inside a namespace
+  package (as defined by :pep:`420`). To do this, specify the import name of the
+  concrete, inner module you are packaging - e.g. ``name = "sphinxcontrib.foo"``
+  - either in the ``[project]`` table, or under ``[tool.flit.module]`` if you
+  want to use a different name on PyPI (:ghpull:`468`).
+- Flit no longer generates a ``setup.py`` file in sdists (``.tar.gz`` packages)
+  by default (:ghpull:`462`). Modern packaging tools don't need this. You can
+  use the ``--setup-py`` flag to keep adding it for now, but this will probably
+  be removed at some point in the future.
+- Fixed how ``flit init`` handles authors' names with non-ASCII characters
+  (:ghpull:`460`).
+- When ``flit init`` generates a LICENSE file, the new ``pyproject.toml`` now
+  references it (:ghpull:`467`).
+
+Version 3.4
+-----------
+
+- Python 3.6 or above is now required, both for ``flit`` and ``flit_core``.
+- Add a ``--setup-py`` option to ``flit build`` and ``flit publish``, and a
+  warning when neither this nor ``--no-setup-py`` are specified (:ghpull:`431`).
+  A future version will stop generating ``setup.py`` files in sdists by default.
+- Add support for standardised editable installs - ``pip install -e`` -
+  according to :pep:`660` (:ghpull:`400`).
+- Add a ``--pypirc`` option for ``flit publish`` to specify an alternative path
+  to a ``.pypirc`` config file describing package indexes (:ghpull:`434`).
+- Fix installing dependencies specified in a ``[project]`` table (:ghpull:`433`).
+- Fix building wheels when ``SOURCE_DATE_EPOCH`` (see :doc:`reproducible`) is
+  set to a date before 1980 (:ghpull:`448`).
+- Switch to using the `tomli <https://pypi.org/project/tomli/>`_ TOML parser,
+  in common with other packaging projects (:ghpull:`438`).
+  This supports TOML version 1.0.
+- Add a document on :doc:`bootstrap` (:ghpull:`441`).
+
+Version 3.3
+-----------
+
+- ``PKG-INFO`` files in sdists are now generated the same way as ``METADATA`` in
+  wheels, fixing some issues with sdists (:ghpull:`410`).
+- ``flit publish`` now sends SHA-256 hashes, fixing uploads to GitLab package
+  repositories (:ghpull:`416`).
+- The ``[project]`` metadata table from :pep:`621` is now fully supported and
+  :ref:`documented <pyproject_toml_project>`. Projects using this can now
+  specify ``requires = ["flit_core >=3.2,<4"]`` in the ``[build-system]`` table.
+
+Version 3.2
+-----------
+
+- Experimental support for specifying metadata in a ``[project]`` table in
+  ``pyproject.toml`` as specified by :pep:`621` (:ghpull:`393`). If you try
+  using this, please specify ``requires = ["flit_core >=3.2.0,<3.3"]`` in the
+  ``[build-system]`` table for now, in case it needs to change for the next
+  release.
+- Fix writing METADATA file with multi-line information in certain fields
+  such as ``Author`` (:ghpull:`402`).
+- Fix building wheel when a directory such as LICENSES appears in the project
+  root directory (:ghpull:`401`).
+
+Version 3.1
+-----------
+
+- Update handling of names & version numbers in wheel filenames and
+  ``.dist-info`` folders in line with changes in the specs (:ghpull:`395`).
+- Switch from the deprecated ``pytoml`` package to ``toml`` (:ghpull:`378`).
+- Fix specifying backend-path in ``pyproject.toml`` for flit-core (as a list
+  instead of a string).
+
+Version 3.0
+-----------
+
+Breaking changes:
+
+- Projects must now provide Flit with information in ``pyproject.toml`` files,
+  not the older ``flit.ini`` format (:ghpull:`338`).
+- ``flit_core`` once again requires Python 3 (>=3.4). Packages that support
+  Python 2 can still be built by ``flit_core`` 2.x, but can't rely on new
+  features (:ghpull:`342`).
+- The deprecated ``flit installfrom`` command was removed (:ghpull:`334`).
+  You can use ``pip install git+https://github.com/...`` instead.
+
+Features and fixes:
+
+- Fix building sdists from a git repository with non-ASCII characters in
+  filenames (:ghpull:`346`).
+- Fix identifying the version number when the code contains a subscript
+  assignment before ``__version__ =`` (:ghpull:`348`).
+- Script entry points can now use a class method (:ghpull:`359`).
+- Set suitable permission bits on metadata files in wheels (:ghpull:`256`).
+- Fixed line endings in the ``RECORD`` file when installing on Windows
+  (:ghpull:`368`).
+- Support for recording the source of local installations, as in :pep:`610`
+  (:ghpull:`335`).
+- ``flit init`` will check for a README in the root of the project and
+  automatically set it as ``description-file`` (:ghpull:`337`).
+- Pygments is not required for checking reStructuredText READMEs (:ghpull:`357`).
+- Packages where the version number can be recognised without executing their
+  code don't need their dependencies installed to build, which should make them
+  build faster (:ghpull:`361`).
+- Ensure the installed ``RECORD`` file is predictably ordered (:ghpull:`366`).
+
+Version 2.3
+-----------
+
+- New projects created with :ref:`init_cmd` now declare that they require
+  ``flit_core >=2,<4`` (:ghpull:`328`). Any projects using ``pyproject.toml``
+  (not ``flit.ini``) should be compatible with flit 3.x.
+- Fix selecting files from a git submodule to include in an sdist
+  (:ghpull:`324`).
+- Fix checking classifiers when no writeable cache directory is available
+  (:ghpull:`319`).
+- Better errors when trying to install to a mis-spelled or missing Python
+  interpreter (:ghpull:`331`).
+- Fix specifying ``--repository`` before ``upload`` (:ghpull:`322`). Passing the
+  option like this is deprecated, and you should now pass it after ``upload``.
+- Documentation improvements (:ghpull:`327`, :ghpull:`318`, :ghpull:`314`)
+
+Version 2.2
+-----------
+
+- Allow underscores in package names with Python 2 (:ghpull:`305`).
+- Add a ``--no-setup-py`` option to build sdists without a backwards-compatible
+  ``setup.py`` file (:ghpull:`311`).
+- Fix the generated ``setup.py`` file for packages using a ``src/`` layout
+  (:ghpull:`303`).
+- Fix detecting when more than one file matches the module name specified
+  (:ghpull:`307`).
+- Fix installing to a venv on Windows with the ``--python`` option
+  (:ghpull:`300`).
+- Don't echo the command in scripts installed with ``--symlink`` or
+  ``--pth-file`` on Windows (:ghpull:`310`).
+- New ``bootstrap_dev.py`` script to set up a development installation of Flit
+  from the repository (:ghpull:`301`, :ghpull:`306`).
+
+Version 2.1
+-----------
+
+- Use compression when adding files to wheels.
+- Added the :envvar:`FLIT_INSTALL_PYTHON` environment variable (:ghpull:`295`),
+  to configure flit to always install into a Python other than the one it's
+  running on.
+- ``flit_core`` uses the ``intreehooks`` shim package to load its bootstrapping
+  backend, until a released version of pip supports the standard
+  ``backend-path`` mechanism.
+
+Version 2.0
+-----------
+
+Flit 2 is a major architecture change. The ``flit_core`` package now provides
+a :pep:`517` backend for building packages, while ``flit`` is a
+:doc:`command line interface <cmdline>` extending that.
+
+The build backend works on Python 2, so tools like pip should be able to install
+packages built with flit from source on Python 2.
+The ``flit`` command requires Python 3.5 or above.
+You will need to change the build-system table in your ``pyproject.toml`` file
+to look like this:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["flit_core >=2,<4"]
+    build-backend = "flit_core.buildapi"
+
+Other changes include:
+
+- Support for storing your code under a ``src/`` folder (:ghpull:`260`).
+  You don't need to change any configuration if you do this.
+- Options to control what files are included in an sdist - see
+  :ref:`pyproject_toml_sdist` for the details.
+- Requirements can specify a URL 'direct reference', as an alternative to a
+  version number, with the syntax defined in :pep:`440`:
+  ``requests @ https://example.com/requests-2.22.0.tar.gz``.
+- Fix the shebang of scripts installed with the ``--python`` option and the
+  ``--symlink`` flag (:ghpull:`286`).
+- Installing with ``--deps develop`` now installs normal dependencies
+  as well as development dependencies.
+- Author email is no longer required in the metadata table (:ghpull:`289`).
+- More error messages are now shown without a traceback (:ghpull:`254`)
+
+Version 1.3
+-----------
+
+- Fix for building sdists from a subdirectory in a Mercurial repository
+  (:ghpull:`233`).
+- Fix for getting the docstring and version from modules defining their encoding
+  (:ghpull:`239`).
+- Fix for installing packages with ``flit installfrom`` (:ghpull:`221`).
+- Packages with requirements no longer get a spurious ``Provides-Extra: .none``
+  metadata entry (:ghissue:`228`).
+- Better check of whether ``python-requires`` includes any Python 2 version
+  (:ghpull:`232`).
+- Better check of home page URLs in ``flit init`` (:ghpull:`230`).
+- Better error message when the description file is not found (:ghpull:`234`).
+- Updated a help message to refer to ``pyproject.toml`` (:ghpull:`240`).
+- Improve tests of ``flit init`` (:ghpull:`229`).
+
+Version 1.2.1
+-------------
+
+- Fix for installing packages with ``flit install``.
+- Make ``requests_download`` an extra dependency, to avoid a circular build
+  dependency. To use ``flit installfrom``, you can install with
+  ``pip install flit[installfrom]``. Note that the ``installfrom`` subcommand
+  is deprecated, as it will soon be possible to use pip to install Flit projects
+  directly from a VCS URL.
+
+Version 1.2
+-----------
+
+- Fixes for packages specifying ``requires-extra``: sdists should now work, and
+  environment markers can be used together with ``requires-extra``.
+- Fix running ``flit installfrom`` without a config file present in the
+  working directory.
+- The error message for a missing or empty docstring tells you what file
+  the docstring should be in.
+- Improvements to documentation on version selectors for requirements.
+
+Version 1.1
+-----------
+
+- Packages can now have 'extras', specified as ``requires-extra`` in the
+  :doc:`pyproject.toml file <pyproject_toml>`. These are additional dependencies
+  for optional features.
+- The ``home-page`` metadata field is no longer required.
+- Additional project URLs are now validated.
+- ``flit -V`` is now equivalent to ``flit --version``.
+- Various improvements to documentation.
+
+Version 1.0
+-----------
+
+- The description file may now be written in reStructuredText, Markdown or
+  plain text. The file extension should indicate which of these formats it is
+  (``.rst``, ``.md`` or ``.txt``). Previously, only reStructuredText was
+  officially supported.
+- Multiple links (e.g. documentation, bug tracker) can now be specified in a
+  new :ref:`[tool.flit.metadata.urls] section <pyproject_toml_urls>` of
+  ``pyproject.toml``.
+- Dependencies are now correctly installed to the target Python when you use
+  the ``--symlink`` or ``--pth-file`` options.
+- Dependencies are only installed to the Python where Flit is running if
+  it fails to get the docstring and version number without them.
+- The commands deprecated in 0.13—``flit wheel``, ``flit sdist`` and
+  ``flit register``—have been removed.
+
+Although version 1.0 sounds like a milestone, there's nothing that makes this
+release especially significant. It doesn't represent a step change in stability
+or completeness. Flit has been gradually maturing for some time, and I chose
+this point to end the series of 0.x version numbers.
+
+Version 0.13
+------------
+
+- Better validation of several metadata fields (``dist-name``, ``requires``,
+  ``requires-python``, ``home-page``), and of the version number.
+- New :envvar:`FLIT_ALLOW_INVALID` environment variable to ignore validation
+  failures in case they go wrong.
+- The list of valid classifiers is now fetched from Warehouse (https://pypi.org),
+  rather than the older https://pypi.python.org site.
+- Deprecated ``flit wheel`` and ``flit sdist`` subcommands: use
+  :ref:`build_cmd`.
+- Deprecated ``flit register``: you can no longer register a package separately
+  from uploading it.
+
+Version 0.12.3
+--------------
+
+- Fix building and installing packages with a ``-`` in the distribution name.
+- Fix numbering in README.
+
+Version 0.12.2
+--------------
+
+- New tool to convert ``flit.ini`` to ``pyproject.toml``::
+
+      python3 -m flit.tomlify
+
+- Use the PAX tar format for sdists, as specified by PEP 517.
+
+Version 0.12.1
+--------------
+
+- Restore dependency on ``zipfile36`` backport package.
+- Add some missing options to documentation of ``flit install`` subcommand.
+- Rearrange environment variables in the docs.
+
+Version 0.12
+------------
+
+- Switch the config to ``pyproject.toml`` by default instead of ``flit.ini``,
+  and implement the PEP 517 API.
+- A new option ``--pth-file`` allows for development installation on Windows
+  (where ``--symlink`` usually won't work).
+- Normalise file permissions in the zip file, making builds more reproducible
+  across different systems.
+- Sdists (.tar.gz packages) can now also be reproducibly built by setting
+  :envvar:`SOURCE_DATE_EPOCH`.
+- For most modules, Flit can now extract the version number and docstring
+  without importing it. It will still fall back to importing where getting
+  these from the AST fails.
+- ``flit build`` will build the wheel from the sdist, helping to ensure that
+  files aren't left out of the sdist.
+- All list fields in the INI file now ignore blank lines (``requires``,
+  ``dev-requires``, ``classifiers``).
+- Fix the path separator in the ``RECORD`` file of a wheel built on Windows.
+- Some minor fixes to building reproducible wheels.
+- If building a wheel fails, the temporary file created will be cleaned up.
+- Various improvements to docs and README.
+
+Version 0.11.4
+--------------
+
+- Explicitly open various files as UTF-8, rather than relying on locale
+  encoding.
+- Link to docs from README.
+- Better test coverage, and a few minor fixes for problems revealed by tests.
+
+Version 0.11.3
+--------------
+
+- Fixed a bug causing failed uploads when the password is entered in the
+  terminal.
+
+Version 0.11.2
+--------------
+
+- A couple of behaviour changes when uploading to warehouse.
+
+Version 0.11.1
+--------------
+
+- Fixed a bug when you use flit to build an sdist from a subdirectory inside a
+  VCS checkout. The VCS is now correctly detected.
+- Fix the rst checker for newer versions of docutils, by upgrading the bundled
+  copy of readme_renderer.
+
+Version 0.11
+------------
+
+- Flit can now build sdists (tarballs) and upload them to PyPI, if your code is
+  in a git or mercurial repository. There are new commands:
+
+  - ``flit build`` builds both a wheel and an sdist.
+  - ``flit publish`` builds and uploads a wheel and an sdist.
+
+- Smarter ways of getting the information needed for upload:
+
+  - If you have the `keyring <https://github.com/jaraco/keyring>`_ package
+    installed, flit can use it to store your password, rather than keeping it
+    in plain text in ``~/.pypirc``.
+  - If ``~/.pypirc`` does not already exist, and you are prompted for your
+    username, flit will write it into that file.
+  - You can provide the information as environment variables:
+    :envvar:`FLIT_USERNAME`, :envvar:`FLIT_PASSWORD` and :envvar:`FLIT_INDEX_URL`.
+    Use this to upload packages from a CI service, for instance.
+
+- Include 'LICENSE' or 'COPYING' files in wheels.
+- Fix for ``flit install --symlink`` inside a virtualenv.
+
+
+Version 0.10
+------------
+
+- Downstream packagers can use the :envvar:`FLIT_NO_NETWORK` environment
+  variable to stop flit downloading data from the network.
+
+Version 0.9
+-----------
+
+- ``flit install`` and ``flit installfrom`` now take an optional ``--python`` argument,
+  with the path to the Python executable you want to install it for.
+  Using this, you can install modules to Python 2.
+- Installing a module normally (without ``--symlink``) builds a wheel and uses
+  pip to install it, which should work better in some corner cases.
+
+Version 0.8
+-----------
+
+- A new ``flit installfrom`` subcommand to install a project from a source
+  archive, such as from Github.
+- :doc:`Reproducible builds <reproducible>` - you can produce byte-for-byte
+  identical wheels.
+- A warning for non-canonical version numbers according to `PEP 440
+  <https://www.python.org/dev/peps/pep-0440/>`__.
+- Fix for installing projects on Windows.
+- Better error message when module docstring is only whitespace.
+
+Version 0.7
+-----------
+
+- A new ``dev-requires`` field in the config file for development requirements,
+  used when doing ``flit install``.
+- Added a ``--deps`` option for ``flit install`` to control which dependencies
+  are installed.
+- Flit can now be invoked with ``python -m flit``.
+
+Version 0.6
+-----------
+
+- ``flit install`` now ensures requirements specified in ``flit.ini`` are
+  installed, using pip.
+- If you specify a description file, flit now warns you if it's not valid
+  reStructuredText (since invalid reStructuredText is treated as plain text on
+  PyPI).
+- Improved the error message for mis-spelled keys in ``flit.ini``.
+
+Version 0.5
+-----------
+
+- A new ``flit init`` command to quickly define the essential basic metadata
+  for a package.
+- Support for entry points.
+- A new ``flit register`` command to register a package without uploading it,
+  for when you want to claim a name before you're ready to release.
+- Added a ``--repository`` option for specifying an alternative PyPI instance.
+- Added a ``--debug`` flag to show debug-level log messages.
+- Better error messages when the module docstring or ``__version__`` is missing.
+
+Version 0.4
+-----------
+
+- Users can now specify ``dist-name`` in the config file if they need to use
+  different names on PyPI and for imports.
+- Classifiers are now checked against a locally cached list of valid
+  classifiers.
+- Packages can be locally installed into environments for development.
+- Local installation now creates a PEP 376 ``.dist-info`` folder instead of
+  ``.egg-info``.
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..9740a9c
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,34 @@
+Flit |version|
+==============
+
+.. raw:: html
+
+   <img src="_static/flit_logo_nobg_cropped.svg" width="200px" style="float: right"/>
+
+.. include:: ../README.rst
+
+Documentation contents
+----------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   pyproject_toml
+   cmdline
+   upload
+   reproducible
+   rationale
+   bootstrap
+
+.. toctree::
+   :maxdepth: 1
+
+   development
+   history
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
+
diff --git a/doc/make.bat b/doc/make.bat
new file mode 100644
index 0000000..965332d
--- /dev/null
+++ b/doc/make.bat
@@ -0,0 +1,242 @@
+@ECHO OFF

+

+REM Command file for Sphinx documentation

+

+if "%SPHINXBUILD%" == "" (

+	set SPHINXBUILD=sphinx-build

+)

+set BUILDDIR=_build

+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .

+set I18NSPHINXOPTS=%SPHINXOPTS% .

+if NOT "%PAPER%" == "" (

+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%

+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%

+)

+

+if "%1" == "" goto help

+

+if "%1" == "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.  text       to make text files

+	echo.  man        to make manual pages

+	echo.  texinfo    to make Texinfo files

+	echo.  gettext    to make PO message catalogs

+	echo.  changes    to make an overview over 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

+	goto end

+)

+

+if "%1" == "clean" (

+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i

+	del /q /s %BUILDDIR%\*

+	goto end

+)

+

+

+%SPHINXBUILD% 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

+)

+

+if "%1" == "html" (

+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.

+	goto end

+)

+

+if "%1" == "dirhtml" (

+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.

+	goto end

+)

+

+if "%1" == "singlehtml" (

+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.

+	goto end

+)

+

+if "%1" == "pickle" (

+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished; now you can process the pickle files.

+	goto end

+)

+

+if "%1" == "json" (

+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished; now you can process the JSON files.

+	goto end

+)

+

+if "%1" == "htmlhelp" (

+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp

+	if errorlevel 1 exit /b 1

+	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

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished; now you can run "qcollectiongenerator" with the ^

+.qhcp project file in %BUILDDIR%/qthelp, like this:

+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Flit.qhcp

+	echo.To view the help file:

+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Flit.ghc

+	goto end

+)

+

+if "%1" == "devhelp" (

+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished.

+	goto end

+)

+

+if "%1" == "epub" (

+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished. The epub file is in %BUILDDIR%/epub.

+	goto end

+)

+

+if "%1" == "latex" (

+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.

+	goto end

+)

+

+if "%1" == "latexpdf" (

+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex

+	cd %BUILDDIR%/latex

+	make all-pdf

+	cd %BUILDDIR%/..

+	echo.

+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.

+	goto end

+)

+

+if "%1" == "latexpdfja" (

+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex

+	cd %BUILDDIR%/latex

+	make all-pdf-ja

+	cd %BUILDDIR%/..

+	echo.

+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.

+	goto end

+)

+

+if "%1" == "text" (

+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished. The text files are in %BUILDDIR%/text.

+	goto end

+)

+

+if "%1" == "man" (

+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished. The manual pages are in %BUILDDIR%/man.

+	goto end

+)

+

+if "%1" == "texinfo" (

+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.

+	goto end

+)

+

+if "%1" == "gettext" (

+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.

+	goto end

+)

+

+if "%1" == "changes" (

+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.The overview file is in %BUILDDIR%/changes.

+	goto end

+)

+

+if "%1" == "linkcheck" (

+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck

+	if errorlevel 1 exit /b 1

+	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

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Testing of doctests in the sources finished, look at the ^

+results in %BUILDDIR%/doctest/output.txt.

+	goto end

+)

+

+if "%1" == "xml" (

+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished. The XML files are in %BUILDDIR%/xml.

+	goto end

+)

+

+if "%1" == "pseudoxml" (

+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml

+	if errorlevel 1 exit /b 1

+	echo.

+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.

+	goto end

+)

+

+:end

diff --git a/doc/pyproject_toml.rst b/doc/pyproject_toml.rst
new file mode 100644
index 0000000..18d1d26
--- /dev/null
+++ b/doc/pyproject_toml.rst
@@ -0,0 +1,480 @@
+The pyproject.toml config file
+==============================
+
+This file lives next to the module or package.
+
+.. note::
+
+   Older version of Flit (up to 0.11) used a :doc:`flit.ini file <flit_ini>` for
+   similar information. These files no longer work with Flit 3 and above.
+
+   Run ``python3 -m flit.tomlify`` to convert a ``flit.ini`` file to
+   ``pyproject.toml``.
+
+Build system section
+--------------------
+
+This tells tools like pip to build your project with flit. It's a standard
+defined by PEP 517. For any new project using Flit, it will look like this:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["flit_core >=3.2,<4"]
+    build-backend = "flit_core.buildapi"
+
+Version constraints:
+
+- For now, all packages should specify ``<4``, so they won't be impacted by
+  changes in the next major version.
+- :ref:`pyproject_toml_project` requires ``flit_core >=3.2``
+- :ref:`pyproject_old_metadata` requires ``flit_core >=2,<4``
+- The older :doc:`flit.ini file <flit_ini>` requires ``flit_core <3``.
+- TOML features new in version 1.0 require ``flit_core >=3.4``.
+- ``flit_core`` 3.3 is the last version supporting Python 3.4 & 3.5. Packages
+  supporting these Python versions can only use `TOML v0.5
+  <https://toml.io/en/v0.5.0>`_.
+- Only ``flit_core`` 2.x can build packages on Python 2, so packages still
+  supporting Python 2 cannot use new-style metadata (the ``[project]`` table).
+
+.. _pyproject_toml_project:
+
+New style metadata
+------------------
+
+.. versionadded:: 3.2
+
+The new standard way to specify project metadata is in a ``[project]`` table,
+as defined by :pep:`621`. Flit works for now with either this or the older
+``[tool.flit.metadata]`` table (:ref:`described below <pyproject_old_metadata>`),
+but it won't allow you to mix them.
+
+A simple ``[project]`` table might look like this:
+
+.. code-block:: toml
+
+    [project]
+    name = "astcheck"
+    authors = [
+        {name = "Thomas Kluyver", email = "thomas@kluyver.me.uk"},
+    ]
+    readme = "README.rst"
+    classifiers = [
+        "License :: OSI Approved :: MIT License",
+    ]
+    requires-python = ">=3.5"
+    dynamic = ["version", "description"]
+
+The allowed fields are:
+
+name
+  The name your package will have on PyPI. This field is required. For Flit,
+  this name, with any hyphens replaced by underscores, is also the default value
+  of the import name (see :ref:`pyproject_module` if that needs to be
+  different).
+
+  .. versionchanged:: 3.8
+     Hyphens in the project name are now translated to underscores for the
+     import name.
+version
+  Version number as a string. If you want Flit to get this from a
+  ``__version__`` attribute, leave it out of the TOML config and include
+  "version" in the ``dynamic`` field.
+description
+  A one-line description of your project. If you want Flit to get this from
+  the module docstring, leave it out of the TOML config and include
+  "description" in the ``dynamic`` field.
+readme
+  A path (relative to the .toml file) to a file containing a longer description
+  of your package to show on PyPI. This should be written in `reStructuredText
+  <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_, Markdown or
+  plain text, and the filename should have the appropriate extension
+  (``.rst``, ``.md`` or ``.txt``). Alternatively, ``readme`` can be a table with
+  either a ``file`` key (a relative path) or a ``text`` key (literal text), and
+  an optional ``content-type`` key (e.g. ``text/x-rst``).
+requires-python
+  A version specifier for the versions of Python this requires, e.g. ``~=3.3`` or
+  ``>=3.3,<4``, which are equivalents.
+license
+  A table with either a ``file`` key (a relative path to a license file) or a
+  ``text`` key (the license text).
+authors
+  A list of tables with ``name`` and ``email`` keys (both optional) describing
+  the authors of the project.
+maintainers
+  Same format as authors.
+keywords
+  A list of words to help with searching for your package.
+classifiers
+  A list of `Trove classifiers <https://pypi.python.org/pypi?%3Aaction=list_classifiers>`_.
+  Add ``Private :: Do Not Upload`` into the list to prevent a private package
+  from being uploaded to PyPI by accident.
+dependencies & optional-dependencies
+  See :ref:`pyproject_project_dependencies`.
+urls
+  See :ref:`pyproject_project_urls`.
+scripts & gui-scripts
+  See :ref:`pyproject_project_scripts`.
+entry-points
+  See :ref:`pyproject_project_entrypoints`.
+dynamic
+  A list of field names which aren't specified here, for which Flit should
+  find a value at build time. Only "version" and "description" are accepted.
+
+.. _pyproject_project_dependencies:
+
+Dependencies
+~~~~~~~~~~~~
+
+The ``dependencies`` field is a list of other packages from PyPI that this
+package needs. Each package may be followed by a version specifier like
+``>=4.1``, and/or an `environment marker`_
+after a semicolon. For example:
+
+  .. code-block:: toml
+
+      dependencies = [
+          "requests >=2.6",
+          "configparser; python_version == '2.7'",
+      ]
+
+The ``[project.optional-dependencies]`` table contains lists of packages needed
+for every optional feature. The requirements are specified in the same format as
+for ``dependencies``. For example:
+
+  .. code-block:: toml
+
+      [project.optional-dependencies]
+      test = [
+          "pytest >=2.7.3",
+          "pytest-cov",
+      ]
+      doc = ["sphinx"]
+
+You can call these optional features anything you want, although ``test`` and
+``doc`` are common ones. You specify them for installation in square brackets
+after the package name or directory, e.g. ``pip install '.[test]'``.
+
+.. _pyproject_project_urls:
+
+URLs table
+~~~~~~~~~~
+
+Your project's page on `pypi.org <https://pypi.org/>`_ can show a number of
+links. You can point people to documentation or a bug tracker, for example.
+
+This section is called ``[project.urls]`` in the file. You can use
+any names inside it. Here it is for flit:
+
+.. code-block:: toml
+
+  [project.urls]
+  Documentation = "https://flit.pypa.io"
+  Source = "https://github.com/pypa/flit"
+
+.. _pyproject_project_scripts:
+
+Scripts section
+~~~~~~~~~~~~~~~
+
+This section is called ``[project.scripts]`` in the file.
+Each key and value describes a shell command to be installed along with
+your package. These work like setuptools 'entry points'. Here's the section
+for flit:
+
+.. code-block:: toml
+
+    [project.scripts]
+    flit = "flit:main"
+
+
+This will create a ``flit`` command, which will call the function ``main()``
+imported from :mod:`flit`.
+
+A similar table called ``[project.gui-scripts]`` defines commands which launch
+a GUI. This only makes a difference on Windows, where GUI scripts are run
+without a console.
+
+.. _pyproject_project_entrypoints:
+
+Entry points sections
+~~~~~~~~~~~~~~~~~~~~~
+
+You can declare `entry points <http://entrypoints.readthedocs.io/en/latest/>`_
+using sections named :samp:`[project.entry-points.{groupname}]`. E.g. to
+provide a pygments lexer from your package:
+
+.. code-block:: toml
+
+    [project.entry-points."pygments.lexers"]
+    dogelang = "dogelang.lexer:DogeLexer"
+
+In each ``package:name`` value, the part before the colon should be an
+importable module name, and the latter part should be the name of an object
+accessible within that module. The details of what object to expose depend on
+the application you're extending.
+
+If the group name contains a dot, it must be quoted (``"pygments.lexers"``
+above). Script entry points are defined in :ref:`scripts tables
+<pyproject_project_scripts>`, so you can't use the group names
+``console_scripts`` or ``gui_scripts`` here.
+
+.. _pyproject_module:
+
+Module section
+~~~~~~~~~~~~~~
+
+If your package will have different names for installation and import,
+you should specify the install (PyPI) name in the ``[project]`` table
+(:ref:`see above <pyproject_toml_project>`), and the import name in a
+``[tool.flit.module]`` table:
+
+.. code-block:: toml
+
+    [project]
+    name = "pynsist"
+    # ...
+
+    [tool.flit.module]
+    name = "nsist"
+
+Flit looks for the source of the package by its import name. The source may be
+located either in the directory that holds the ``pyproject.toml`` file, or in a
+``src/`` subdirectory.
+
+.. _pyproject_old_metadata:
+
+Old style metadata
+------------------
+
+Flit's older way to specify metadata is in a ``[tool.flit.metadata]`` table,
+along with ``[tool.flit.scripts]`` and ``[tool.flit.entrypoints]``, described
+below. This is still recognised for now, but you can't mix it with
+:ref:`pyproject_toml_project`.
+
+There are three required fields:
+
+module
+  The name of the module/package, as you'd use in an import statement.
+author
+  Your name
+author-email
+  Your email address
+
+e.g. for flit itself
+
+.. code-block:: toml
+
+    [tool.flit.metadata]
+    module = "flit"
+    author = "Thomas Kluyver"
+    author-email = "thomas@kluyver.me.uk"
+
+.. versionchanged:: 1.1
+
+   ``home-page`` was previously required.
+
+The remaining fields are optional:
+
+home-page
+  A URL for the project, such as its Github repository.
+requires
+  A list of other packages from PyPI that this package needs. Each package may
+  be followed by a version specifier like ``(>=4.1)`` or ``>=4.1``, and/or an
+  `environment marker`_
+  after a semicolon. For example:
+
+  .. code-block:: toml
+
+      requires = [
+          "requests >=2.6",
+          "configparser; python_version == '2.7'",
+      ]
+
+requires-extra
+  Lists of packages needed for every optional feature. The requirements
+  are specified in the same format as for ``requires``. The requirements of
+  the two reserved extras ``test`` and ``doc`` as well as the extra ``dev``
+  are installed by ``flit install``. For example:
+
+  .. code-block:: toml
+
+      [tool.flit.metadata.requires-extra]
+      test = [
+          "pytest >=2.7.3",
+          "pytest-cov",
+      ]
+      doc = ["sphinx"]
+
+  .. versionadded:: 1.1
+
+description-file
+  A path (relative to the .toml file) to a file containing a longer description
+  of your package to show on PyPI. This should be written in `reStructuredText
+  <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_, Markdown or
+  plain text, and the filename should have the appropriate extension
+  (``.rst``, ``.md`` or ``.txt``).
+classifiers
+  A list of `Trove classifiers <https://pypi.python.org/pypi?%3Aaction=list_classifiers>`_.
+  Add ``Private :: Do Not Upload`` into the list to prevent a private package
+  from uploading on PyPI by accident.
+requires-python
+  A version specifier for the versions of Python this requires, e.g. ``~=3.3`` or
+  ``>=3.3,<4`` which are equivalents.
+dist-name
+  If you want your package's name on PyPI to be different from the importable
+  module name, set this to the PyPI name.
+keywords
+  Comma separated list of words to help with searching for your package.
+license
+  The name of a license, if you're using one for which there isn't a Trove
+  classifier. It's recommended to use Trove classifiers instead of this in
+  most cases.
+maintainer, maintainer-email
+  Like author, for if you've taken over a project from someone else.
+
+Here was the metadata section from flit using the older style:
+
+.. code-block:: toml
+
+    [tool.flit.metadata]
+    module="flit"
+    author="Thomas Kluyver"
+    author-email="thomas@kluyver.me.uk"
+    home-page="https://github.com/pypa/flit"
+    requires=[
+        "flit_core >=2.2.0",
+        "requests",
+        "docutils",
+        "tomli",
+        "tomli-w",
+    ]
+    requires-python=">=3.6"
+    description-file="README.rst"
+    classifiers=[
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: BSD License",
+        "Programming Language :: Python :: 3",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ]
+
+.. _pyproject_toml_urls:
+
+URLs subsection
+~~~~~~~~~~~~~~~
+
+Your project's page on `pypi.org <https://pypi.org/>`_ can show a number of
+links, in addition to the ``home-page`` URL described above. You can
+point people to documentation or a bug tracker, for example.
+
+This section is called ``[tool.flit.metadata.urls]`` in the file. You can use
+any names inside it. Here it is for flit:
+
+.. code-block:: toml
+
+  [tool.flit.metadata.urls]
+  Documentation = "https://flit.pypa.io"
+
+.. versionadded:: 1.0
+
+.. _pyproject_toml_scripts:
+
+Scripts section
+~~~~~~~~~~~~~~~
+
+A ``[tool.flit.scripts]`` table can be used along with ``[tool.flit.metadata]``.
+It is in the same format as the newer ``[project.scripts]`` table
+:ref:`described above <pyproject_project_scripts>`.
+
+Entry points sections
+~~~~~~~~~~~~~~~~~~~~~
+
+``[tool.flit.entrypoints]`` tables can be used along with ``[tool.flit.metadata]``.
+They are in the same format as the newer ``[project.entry-points]`` tables
+:ref:`described above <pyproject_project_entrypoints>`.
+
+.. _pyproject_toml_sdist:
+
+Sdist section
+-------------
+
+.. versionadded:: 2.0
+
+When you use :ref:`build_cmd` or :ref:`publish_cmd`, Flit builds an sdist
+(source distribution) tarball containing the files that are checked into version
+control (git or mercurial). If you want more control, or it doesn't recognise
+your version control system, you can give lists of paths or glob patterns as
+``include`` and ``exclude`` in this section. For example:
+
+.. code-block:: toml
+
+    [tool.flit.sdist]
+    include = ["doc/"]
+    exclude = ["doc/*.html"]
+
+These paths:
+
+- Always use ``/`` as a separator (POSIX style)
+- Must be relative paths from the directory containing ``pyproject.toml``
+- Cannot go outside that directory (no ``../`` paths)
+- Cannot contain control characters or ``<>:"\\``
+- Can refer to directories, in which case they include everything under the
+  directory, including subdirectories
+- Should match the case of the files they refer to, as case-insensitive matching
+  is platform dependent
+
+.. versionchanged:: 3.8
+   Include and exclude patterns can now use recursive glob patterns (``**``).
+
+Exclusions have priority over inclusions. Bytecode is excluded by default and cannot
+be included.
+
+.. note::
+
+   If you are not using :ref:`build_cmd` but  ``flit_core`` via another build
+   frontend, Flit doesn't doesn't check the VCS for files to include but instead
+   builds a 'minimal' sdist (which includes the files necessary to build a wheel).
+   You'll have to adapt your inclusion/exclusion rules to achieve the same result
+   as you'd get with :ref:`build_cmd`.
+
+.. _pyproject_toml_external_data:
+
+External data section
+---------------------
+
+.. versionadded:: 3.7
+
+Data files which your code will use should go inside the Python package folder.
+Flit will package these with no special configuration.
+
+However, sometimes it's useful to package external files for system integration,
+such as man pages or files defining a Jupyter extension. To do this, arrange
+the files within a directory such as ``data``, next to your ``pyproject.toml``
+file, and add a section like this:
+
+.. code-block:: toml
+
+    [tool.flit.external-data]
+    directory = "data"
+
+Paths within this directory are typically installed to corresponding paths under
+a prefix (such as a virtualenv directory). E.g. you might save a man page for a
+script as ``(data)/share/man/man1/foo.1``.
+
+Whether these files are detected by the systems they're meant to integrate with
+depends on how your package is installed and how those systems are configured.
+For instance, installing in a virtualenv usually doesn't affect anything outside
+that environment. Don't rely on these files being picked up unless you have
+close control of how the package will be installed.
+
+If you install a package with ``flit install --symlink``, a symlink is made
+for each file in the external data directory. Otherwise (including development
+installs with ``pip install -e``), these files are copied to their destination,
+so changes here won't take effect until you reinstall the package.
+
+.. note::
+
+   For users coming from setuptools: external data corresponds to setuptools'
+   ``data_files`` parameter, although setuptools offers more flexibility.
+
+.. _environment marker: https://www.python.org/dev/peps/pep-0508/#environment-markers
diff --git a/doc/rationale.rst b/doc/rationale.rst
new file mode 100644
index 0000000..559f79e
--- /dev/null
+++ b/doc/rationale.rst
@@ -0,0 +1,58 @@
+Why use Flit?
+=============
+
+*Make the easy things easy and the hard things possible* is an old motto from
+the Perl community. Flit is entirely focused on the *easy things* part of that,
+and leaves the hard things up to other tools.
+
+Specifically, the easy things are pure Python packages with no build steps
+(neither compiling C code, nor bundling Javascript, etc.). The vast majority of
+packages on PyPI are like this: plain Python code, with maybe some static data
+files like icons included.
+
+It's easy to underestimate the challenges involved in distributing and
+installing code, because it seems like you just need to copy some files into
+the right place. There's a whole lot of metadata and tooling that has to work
+together around that fundamental step. But with the right tooling, a developer
+who wants to release their code doesn't need to know about most of that.
+
+What, specifically, does Flit make easy?
+
+- ``flit init`` helps you set up the information Flit needs about your
+  package.
+- Subpackages are automatically included: you only need to specify the
+  top-level package.
+- Data files within a package directory are automatically included.
+  Missing data files has been a common packaging mistake with other tools.
+- The version number is taken from your package's ``__version__`` attribute,
+  so that always matches the version that tools like pip see.
+- ``flit publish`` uploads a package to PyPI, so you don't need a separate tool
+  to do this.
+
+Setuptools, the most common tool for Python packaging, now has shortcuts for
+many of the same things. But it has to stay compatible with projects published
+many years ago, which limits what it can do by default.
+
+Flit also has some support for :doc:`reproducible builds <reproducible>`,
+a feature which some people care about.
+
+There have been many other efforts to improve the user experience of Python
+packaging, such as `pbr <https://pypi.org/project/pbr/>`_, but before Flit,
+these tended to build on setuptools and distutils. That was a pragmatic
+decision, but it's hard to build something radically different on top of those
+libraries. The existence of Flit spurred the development of new standards,
+like :pep:`518` and :pep:`517`, which are now used by other packaging tools
+such as `Poetry <https://python-poetry.org/>`_ and
+`Enscons <https://pypi.org/project/enscons/>`_.
+
+Other options
+-------------
+
+If your package needs a build step, you won't be able to use Flit.
+`Setuptools <https://setuptools.readthedocs.io/en/latest/>`_ is the de-facto
+standard, but newer tools such as Enscons_ also cover this case.
+
+Flit also doesn't help you manage dependencies: you have to add them to
+``pyproject.toml`` by hand. Tools like Poetry_ and `Pipenv
+<https://pypi.org/project/pipenv/>`_ have features which help add and update
+dependencies on other packages.
diff --git a/doc/reproducible.rst b/doc/reproducible.rst
new file mode 100644
index 0000000..2894fc8
--- /dev/null
+++ b/doc/reproducible.rst
@@ -0,0 +1,34 @@
+Reproducible builds
+===================
+
+.. versionadded:: 0.8
+
+Wheels built by flit are reproducible: if you build from the same source code,
+you should be able to make wheels that are exactly identical, byte for byte.
+This is useful for verifying software. For more details, see
+`reproducible-builds.org <https://reproducible-builds.org/>`__.
+
+There is a caveat, however: wheels (which are zip files) include the
+modification timestamp from each file. This will
+probably be different on each computer, because it indicates when your local
+copy of the file was written, not when it was changed in version control.
+These timestamps can be overridden by the environment variable
+:envvar:`SOURCE_DATE_EPOCH`.
+
+.. code-block:: shell
+
+   SOURCE_DATE_EPOCH=$(date +%s)
+   flit publish
+   # Record the value of SOURCE_DATE_EPOCH in release notes for reproduction
+
+.. versionchanged:: 0.12
+   Normalising permission bits
+
+Flit normalises the permission bits of files copied into a wheel to either
+755 (executable) or 644. This means that a file is readable by all users
+and writable only by the user who owns it.
+
+The most popular version control systems only track the executable bit,
+so checking out the same repository on systems with different umasks
+(e.g. Debian and Fedora) produces files with different permissions. With Flit
+0.11 and earlier, this difference would produce non-identical wheels.
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 0000000..87126c9
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,3 @@
+sphinx ~= 4.2
+sphinxcontrib_github_alt ~= 1.2
+sphinx-rtd-theme ~= 1.0
diff --git a/doc/upload.rst b/doc/upload.rst
new file mode 100644
index 0000000..df5af5e
--- /dev/null
+++ b/doc/upload.rst
@@ -0,0 +1,77 @@
+Controlling package uploads
+===========================
+
+.. program:: flit publish
+
+The command ``flit publish`` will upload your package to a package index server.
+The default settings let you upload to `PyPI <https://pypi.org/>`_,
+the default Python Package Index, with a single user account.
+
+If you want to upload to other servers, or with more than one user account,
+or upload packages from a continuous integration job,
+you can configure Flit in two main ways:
+
+Using .pypirc
+-------------
+
+You can create or edit a config file in your home directory, ``~/.pypirc`` that
+will be used by default or you can specify a custom location.
+This is also used by other Python tools such as `twine
+<https://pypi.python.org/pypi/twine>`_.
+
+For instance, to upload a package to the `Test PyPI server <https://test.pypi.org/>`_
+instead of the normal PyPI, use a config file looking like this:
+
+.. code-block:: ini
+
+    [distutils]
+    index-servers =
+       pypi
+       testpypi
+
+    [pypi]
+    repository = https://upload.pypi.org/legacy/
+    username = sirrobin  # Replace with your PyPI username
+
+    [testpypi]
+    repository = https://test.pypi.org/legacy/
+    username = sirrobin  # Replace with your TestPyPI username
+
+You can select an index server from this config file with the
+:option:`--repository` option::
+
+    flit publish --repository testpypi
+
+If you don't use this option,
+Flit will use the server called ``pypi`` in the config file. If that doesn't
+exist, it uploads to PyPI at ``https://upload.pypi.org/legacy/`` by default.
+
+If you publish a package and you don't have a ``.pypirc`` file, Flit will create
+it to store your username.
+
+Flit tries to store your password securely using the
+`keyring <https://pypi.python.org/pypi/keyring>`_ library.
+If keyring is not installed, Flit will ask for your password for each upload.
+Alternatively, you can also manually add your password to the ``.pypirc`` file
+(``password = ...``)
+
+.. _upload_envvars:
+
+Using environment variables
+---------------------------
+
+You can specify a server to upload to with :envvar:`FLIT_INDEX_URL`, and
+pass credentials with :envvar:`FLIT_USERNAME` and :envvar:`FLIT_PASSWORD`.
+Environment variables take precedence over the config file, except if you use
+the :option:`--repository` option to explicitly pick a server from the config file.
+
+This can make it easier to automate uploads, for example to release packages
+from a continuous integration job.
+
+.. warning::
+
+   Storing a password in an environment variable is convenient, but it's
+   `easy to accidentally leak it <https://www.diogomonica.com/2017/03/27/why-you-shouldnt-use-env-variables-for-secret-data/>`_.
+   Look out for scripts that helpfully print all environment variables for
+   debugging, and remember that other scripts and libraries you run in
+   that environment have access to your password.