summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/Makefile177
-rw-r--r--doc/_static/flit_logo_nobg.svg149
-rw-r--r--doc/_static/flit_logo_nobg_cropped.pngbin0 -> 5890 bytes
-rw-r--r--doc/_static/flit_logo_nobg_cropped.svg158
-rw-r--r--doc/bootstrap.rst41
-rw-r--r--doc/cmdline.rst262
-rw-r--r--doc/conf.py264
-rw-r--r--doc/development.rst26
-rw-r--r--doc/flit_ini.rst113
-rw-r--r--doc/history.rst497
-rw-r--r--doc/index.rst34
-rw-r--r--doc/make.bat242
-rw-r--r--doc/pyproject_toml.rst480
-rw-r--r--doc/rationale.rst58
-rw-r--r--doc/reproducible.rst34
-rw-r--r--doc/requirements.txt3
-rw-r--r--doc/upload.rst77
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
Binary files differ
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.