[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[RFC qemu.qmp PATCH 06/24] Move README.rst to INDEX.rst and update
From: |
John Snow |
Subject: |
[RFC qemu.qmp PATCH 06/24] Move README.rst to INDEX.rst and update |
Date: |
Wed, 15 Dec 2021 16:06:16 -0500 |
The intent is to use README.rst as the new package-level readme that
will be bundled with the source; so move the old "git level readme" over
to INDEX.rst instead, and update it accordingly.
This is primarily here to just document and explain what all the little
bits and pieces of files in the root are and what they do. I find this
stuff helpful when I wander over into other projects, so I'd like to
extend the same courtesy.
Signed-off-by: John Snow <jsnow@redhat.com>
---
README.rst => INDEX.rst | 49 +++++++++++------------------------------
MANIFEST.in | 1 -
2 files changed, 13 insertions(+), 37 deletions(-)
rename README.rst => INDEX.rst (64%)
diff --git a/README.rst b/INDEX.rst
similarity index 64%
rename from README.rst
rename to INDEX.rst
index 9c1fcea..45b0dbf 100644
--- a/README.rst
+++ b/INDEX.rst
@@ -1,9 +1,14 @@
-QEMU Python Tooling
+qemu.qmp File Index
===================
-This directory houses Python tooling used by the QEMU project to build,
-configure, and test QEMU. It is organized by namespace (``qemu``), and
-then by package (e.g. ``qemu/machine``, ``qemu/qmp``, etc).
+This file is here to explain the purpose of all the little bits and
+pieces of project files in the root directory and how they are
+used. It's useful info for those contributing to this project, but not
+so much for those who just want to use the library.
+
+
+Much ado about packaging
+------------------------
``setup.py`` is used by ``pip`` to install this tooling to the current
environment. ``setup.cfg`` provides the packaging configuration used by
@@ -20,7 +25,7 @@ environment. ``setup.cfg`` provides the packaging
configuration used by
If you append the ``--editable`` or ``-e`` argument to either invocation
above, pip will install in "editable" mode. This installs the package as
-a forwarder ("qemu.egg-link") that points to the source tree. In so
+a forwarder ("qemu.qmp.egg-link") that points to the source tree. In so
doing, the installed package always reflects the latest version in your
source tree.
@@ -37,34 +42,6 @@ See `Installing packages using pip and virtual environments
for more information.
-Using these packages without installing them
---------------------------------------------
-
-These packages may be used without installing them first, by using one
-of two tricks:
-
-1. Set your PYTHONPATH environment variable to include this source
- directory, e.g. ``~/src/qemu/python``. See
- https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
-
-2. Inside a Python script, use ``sys.path`` to forcibly include a search
- path prior to importing the ``qemu`` namespace. See
- https://docs.python.org/3/library/sys.html#sys.path
-
-A strong downside to both approaches is that they generally interfere
-with static analysis tools being able to locate and analyze the code
-being imported.
-
-Package installation also normally provides executable console scripts,
-so that tools like ``qmp-shell`` are always available via $PATH. To
-invoke them without installation, you can invoke e.g.:
-
-``> PYTHONPATH=~/src/qemu/python python3 -m qemu.qmp.qmp_shell``
-
-The mappings between console script name and python module path can be
-found in ``setup.cfg``.
-
-
Files in this directory
-----------------------
@@ -72,6 +49,7 @@ Files in this directory
- ``tests/`` Python package tests directory.
- ``avocado.cfg`` Configuration for the Avocado test-runner.
Used by ``make check`` et al.
+- ``INDEX.rst`` you are here!
- ``Makefile`` provides some common testing/installation invocations.
Try ``make help`` to see available targets.
- ``MANIFEST.in`` is read by python setuptools, it specifies additional files
@@ -80,8 +58,7 @@ Files in this directory
- ``Pipfile`` is used by Pipenv to generate ``Pipfile.lock``.
- ``Pipfile.lock`` is a set of pinned package dependencies that this package
is tested under in our CI suite. It is used by ``make check-pipenv``.
-- ``README.rst`` you are here!
-- ``VERSION`` contains the PEP-440 compliant version used to describe
- this package; it is referenced by ``setup.cfg``.
- ``setup.cfg`` houses setuptools package configuration.
- ``setup.py`` is the setuptools installer used by pip; See above.
+- ``VERSION`` contains the PEP-440 compliant version used to describe
+ this package; it is referenced by ``setup.cfg``.
diff --git a/MANIFEST.in b/MANIFEST.in
index 7059ad2..639caae 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,3 +1,2 @@
include VERSION
include PACKAGE.rst
-exclude README.rst
--
2.31.1
- [RFC qemu.qmp PATCH 00/24] Python: Fork qemu.qmp Python lib into independent repo, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 01/24] Fork qemu.qmp from qemu.git, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 03/24] Update maintainer metadata, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 02/24] Update VERSION to 0.0.0a1, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 04/24] Update project description, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 05/24] Update project URLs, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 10/24] Add build and test container to gitlab CI configuration, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 06/24] Move README.rst to INDEX.rst and update,
John Snow <=
- [RFC qemu.qmp PATCH 09/24] Remove sub-dependency pins from Pipfile, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 07/24] Move PACKAGE.rst to README.rst and update, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 08/24] Update Pipfile.lock, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 11/24] Add package build step to GitLab CI, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 12/24] GitLab CI: Add check-dco script, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 13/24] GitLab CI: Add pipenv and tox tests, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 14/24] GitLab CI: Add avocado junit XML output to tests, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 15/24] GitLab CI: Publish python packages to GitLab package repo, John Snow, 2021/12/15
- [RFC qemu.qmp PATCH 17/24] Makefile: add build and publish targets, John Snow, 2021/12/15