Add outline / rough draft of new Overview page (#519)

* adding mostly-skeleton overview * draft talk about frameworks/platforms * expand a little on each section * address most of @ncoghlan's initial review points at #519 * fix @pradyunsg's very valuable copyedits * update title for searchability, add a bit to the binary distribution section, all per @theacodes comments * flesh out sections, clarify zipapp qualification, add a few links * expand image sections, add a few related links * refining a lot of phrasing, expanding on hardware, adding figures * lots of links, and expand on considerations (i think wheels might be the only thing left) * link freezers * more links, slight tweaks to the intro and other language, provide a linked summary of wheels * link to overview from home page * various rephrasals and addition of a couple asides * fix typo * address most copyediting concerns, tweak a header, and add thea's expansion of the modules section. * try to tie sdists and wheels more closely together as recommended practice * new -> separate, add a bit more detail * improve frameworks section intro * add additional encouragement to dual-publish wheels and sdists * adjust heading consistency and add notes for future editors * a few tweaks for flow, plus a favorite quote from Wikipedia for the editors' notes * add link to jupyterlab writing advice
pypa · Aug 12, 2018 · 4b5e860 · 4b5e860
1 parent f93b4c8
commit 4b5e860
Show file tree

Hide file tree

Showing 4 changed files with 518 additions and 2 deletions.
diff --git a/source/assets/py_pkg_applications.png b/source/assets/py_pkg_applications.png
diff --git a/source/assets/py_pkg_tools_and_libs.png b/source/assets/py_pkg_tools_and_libs.png
diff --git a/source/index.rst b/source/index.rst
@@ -6,6 +6,7 @@ Python Packaging User Guide
    :maxdepth: 2
    :hidden:
 
+   overview
    tutorials/index
    guides/index
    discussions/index
@@ -32,8 +33,10 @@ happily accept any :doc:`contributions and feedback <contribute>`. 😊
 Get started
 ===========
 
-Essential tools and concepts for working with the Python packaging ecosystem are
-covered in our :doc:`tutorials/index` section:
+Thinking about shipping a new Python library or application? Start with :doc:`overview`.
+
+Essential tools and concepts for working within the Python
+development ecosystem are covered in our :doc:`tutorials/index` section:
 
 * to learn how to install packages, see the
   :doc:`tutorial on installing packages <tutorials/installing-packages>`.