From 0bf2535fd26d3707574d23765b4be9a543c2708b Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sat, 18 Nov 2023 15:48:51 -0800 Subject: [PATCH 1/3] Restructure table of contents, section indices, and landing page --- source/contribute.rst | 6 +-- source/discussions/index.rst | 6 +-- source/guides/index.rst | 7 ++-- source/index.rst | 75 +++++++++++++++++------------------- source/overview/index.rst | 11 ++++++ source/references/index.rst | 15 ++++++++ source/tutorials/index.rst | 5 +-- 7 files changed, 73 insertions(+), 52 deletions(-) create mode 100644 source/overview/index.rst create mode 100644 source/references/index.rst diff --git a/source/contribute.rst b/source/contribute.rst index a246751e4..e4ee446b1 100644 --- a/source/contribute.rst +++ b/source/contribute.rst @@ -1,8 +1,8 @@ .. |PyPUG| replace:: Python Packaging User Guide -************************ -Contribute to this guide -************************ +************ +Contributing +************ The |PyPUG| welcomes contributors! There are lots of ways to help out, including: diff --git a/source/discussions/index.rst b/source/discussions/index.rst index e5411ece3..f131f5c54 100644 --- a/source/discussions/index.rst +++ b/source/discussions/index.rst @@ -1,7 +1,7 @@ -Discussions -########### +Explanations +============ -**Discussions** are focused on providing comprehensive information about a +**Explanations and Discussions** focus on providing comprehensive information about a specific topic. If you're just trying to get stuff done, see :doc:`/guides/index`. diff --git a/source/guides/index.rst b/source/guides/index.rst index b87d0b1a8..be5a54bbb 100644 --- a/source/guides/index.rst +++ b/source/guides/index.rst @@ -1,7 +1,7 @@ -Guides -###### +How-to Guides +============= -**Guides** are focused on accomplishing a specific task and assume that you are +**How-to Guides** are focused on accomplishing a specific task and assume that you are already familiar with the basics of Python packaging. If you're looking for an introduction to packaging, see :doc:`/tutorials/index`. @@ -13,3 +13,4 @@ introduction to packaging, see :doc:`/tutorials/index`. section-hosting tool-recommendations analyzing-pypi-package-downloads + ../support diff --git a/source/index.rst b/source/index.rst index 32f85b206..b74e297e1 100644 --- a/source/index.rst +++ b/source/index.rst @@ -10,53 +10,42 @@ Python Packaging User Guide :maxdepth: 2 :hidden: - overview - flow + overview/index tutorials/index guides/index discussions/index specifications/index - key_projects - glossary - support + references/index contribute - news -Welcome to the *Python Packaging User Guide*, a collection of tutorials and -references to help you distribute and install Python packages with modern -tools. +Welcome to the *Python Packaging User Guide*. +This collection of tutorials, how-to guides, explanations, specifications, and +references is a central place to learn about Python packages, how to distribute +and install libraries and projects, and build awareness of available modern tools. -This guide is maintained on `GitHub`_ by the :doc:`Python Packaging Authority `. We -happily accept :doc:`contributions and feedback `. 😊 +This guide is maintained on `GitHub`_ by the :doc:`Python Packaging Authority `. +We encourage and happily accept :doc:`contributions `. 😊 .. _GitHub: https://github.com/pypa/packaging.python.org -Overview and Flow -================= +Overview +======== -.. note:: - - Building your understanding of Python packaging is a journey. Patience and - continuous improvement are key to success. The overview and flow sections - provide a starting point for understanding the Python packaging ecosystem. - -The :doc:`overview` explains Python packaging +The :doc:`overview` section provides a high-level view of Python packaging and its use when preparing and distributing projects. -This section helps you build understanding about selecting the tools and -processes that are most suitable for your use case. +This section helps you become familiar with available tools and +processes. It includes what packaging is, the problems that it solves, and key considerations. - To get an overview of the workflow used to publish your code, see :doc:`packaging flow `. Tutorials ========= +Tutorials are the best place to start for anyone new to installing or creating Python Packages. Tutorials walk through the steps needed to complete a project for the first time. -Tutorials aim to help you succeed and provide a starting point for future -exploration. The :doc:`tutorials/index` section includes: * A :doc:`tutorial on installing packages ` @@ -65,29 +54,35 @@ The :doc:`tutorials/index` section includes: * A :doc:`tutorial on packaging and distributing ` your project -Guides -====== +How-to Guides +============= -Guides provide steps to perform a specific task. Guides are more focused on -users who are already familiar with Python packaging and are looking for -specific information. +How-to Guides provide step-by-step instructions to perform a specific task. +These guides are written for users who are already familiar with Python packaging. -The :doc:`guides/index` section provides "how to" instructions in three major -areas: package installation; building and distributing packages; miscellaneous -topics. +The :doc:`guides/index` section is organized in the following areas: -Explanations and Discussions -============================ +* package installation +* building and distributing packages +* miscellaneous topics -The :doc:`discussions/index` section for in-depth explanations and discussion -about topics, such as: +Explanations +============ -* :doc:`discussions/deploying-python-applications` -* :doc:`discussions/pip-vs-easy-install` +The :doc:`Explanations and Discussions ` section presents +in-depth explanations and discussion about a packaging topic. These documents +explain the rationale or "why" something is done. + +Specifications +============== + +The :doc:`specifications/index` section documents the packaging interoperability specifications. Reference ========= -* The :doc:`specifications/index` section for packaging interoperability specifications. +The :doc:`references/index` section describes projects and gives informative information. +These resources typically answer "What is..." questions. The section includes: + * The list of :doc:`other projects ` maintained by members of the Python Packaging Authority. * The :doc:`glossary` for definitions of terms used in Python packaging. diff --git a/source/overview/index.rst b/source/overview/index.rst new file mode 100644 index 000000000..7745740e4 --- /dev/null +++ b/source/overview/index.rst @@ -0,0 +1,11 @@ +Overview +======== + +This section provides a high-level view of Python packaging, its use when +preparing and distributing projects, and its workflows. + +.. toctree:: + :titlesonly: + + ../overview + ../flow diff --git a/source/references/index.rst b/source/references/index.rst new file mode 100644 index 000000000..4f654c170 --- /dev/null +++ b/source/references/index.rst @@ -0,0 +1,15 @@ +Reference +========= + +**Reference** documents define terms and describe information about Python Packaging. + +These documents answer "What is ..." questions for users. +If you're looking for a deeper explanation or discussion about something, +see :doc:`/discussions/index`. + +.. toctree:: + :maxdepth: 1 + + ../key_projects + ../glossary + ../news diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst index 33ab4f98a..e93c3e0e5 100644 --- a/source/tutorials/index.rst +++ b/source/tutorials/index.rst @@ -1,9 +1,8 @@ Tutorials ========= -**Tutorials** are opinionated step-by-step guides to help you get familiar -with packaging concepts. For more detailed information on specific packaging -topics, see :doc:`/guides/index`. +**Tutorials** are the best place to start for anyone new to installing or creating Python Packages. +Tutorials walk through the steps needed to complete a project for the first time. .. toctree:: :maxdepth: 1 From 0e4d8914c7beb4e8a93467d3929fb84e7b0e9e27 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sun, 3 Mar 2024 15:17:15 -0800 Subject: [PATCH 2/3] Update source/tutorials/index.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/tutorials/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst index e93c3e0e5..4837f5891 100644 --- a/source/tutorials/index.rst +++ b/source/tutorials/index.rst @@ -2,7 +2,7 @@ Tutorials ========= **Tutorials** are the best place to start for anyone new to installing or creating Python Packages. -Tutorials walk through the steps needed to complete a project for the first time. +Tutorials walk through the steps needed to complete a project for the first time and avoid presenting you with early decision-making. .. toctree:: :maxdepth: 1 From a0bfe317b1a9bb8a0a0d732891e497c5d595202e Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sun, 3 Mar 2024 15:17:23 -0800 Subject: [PATCH 3/3] Update source/overview/index.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/overview/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/overview/index.rst b/source/overview/index.rst index 7745740e4..8763cccd0 100644 --- a/source/overview/index.rst +++ b/source/overview/index.rst @@ -2,7 +2,7 @@ Overview ======== This section provides a high-level view of Python packaging, its use when -preparing and distributing projects, and its workflows. +preparing and distributing projects, and related workflows. .. toctree:: :titlesonly: