Re: [PATCH v3 04/15] python: add directory structure README.rst files

[John Snow]

On 10/28/20 6:05 PM, Cleber Rosa wrote:
> On Tue, Oct 20, 2020 at 03:35:44PM -0400, John Snow wrote:
> > Add short readmes to python/, python/qemu/, python/qemu/machine, and
> > python/qemu/machine that explain the directory hierarchy. These readmes
> > are visible when browsing the source on e.g. gitlab/github and are
> > designed to help new developers/users quickly make sense of the source
> > tree.
> >
> > They are not designed for inclusion in a published manual.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >   python/README.rst              | 27 +++++++++++++++++++++++++++
> >   python/qemu/README.rst         |  8 ++++++++
> >   python/qemu/machine/README.rst |  9 +++++++++
> >   python/qemu/qmp/README.rst     |  9 +++++++++
> >   4 files changed, 53 insertions(+)
> >   create mode 100644 python/README.rst
> >   create mode 100644 python/qemu/README.rst
> >   create mode 100644 python/qemu/machine/README.rst
> >   create mode 100644 python/qemu/qmp/README.rst
> >
> > diff --git a/python/README.rst b/python/README.rst
> > new file mode 100644
> > index 0000000000..ff40e4c931
> > --- /dev/null
> > +++ b/python/README.rst
> > @@ -0,0 +1,27 @@
> > +QEMU Python Tooling
> > +===================
> > +
> > +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 (``qemu/machine``, ``qemu/qmp``).
> > +
> > +``setup.py`` is used by ``pip`` to install this tooling to the current
> > +environment. You will generally invoke it by doing one of the following:
> > +
> > +1. ``pip3 install .`` will install these packages to your current
> > +   environment. If you are inside a virtual environment, they will
> > +   install there. If you are not, it will attempt to install to the
> > +   global environment, which is not recommended.
> > +
> > +2. ``pip3 install --user .`` will install these packages to your user's
> > +   local python packages. If you are inside of a virtual environment,
> > +   this will fail.
> > +
> > +If you amend the ``-e`` argument, pip will install in "editable" mode;
> > +which installs a version of the package that uses symlinks to these
> > +files, such that the package always reflects the latest version in your
> > +git tree.
> > +
>
> It actually uses *egg-link* files, which are not what people will
> understand by "symlinks".

Ehm, good point; I don't want to *lie* here. I think I do want to avoid 
the jargon though.

"that installs a forwarder pointing to these files" -- better?

> > +See `Installing packages using pip and virtual environments
> > +<https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/>`_
> > +for more information.
> > diff --git a/python/qemu/README.rst b/python/qemu/README.rst
> > new file mode 100644
> > index 0000000000..31209c80a5
> > --- /dev/null
> > +++ b/python/qemu/README.rst
> > @@ -0,0 +1,8 @@
> > +QEMU Python Namespace
> > +=====================
> > +
> > +This directory serves as the root of a `Python PEP 420 implicit
> > +namespace package <<https://www.python.org/dev/peps/pep-0420/>`_.
> > +
> > +Each directory below is assumed to be an installable Python package that
> > +is available under the ``qemu.<package>`` namespace.
> > diff --git a/python/qemu/machine/README.rst b/python/qemu/machine/README.rst
> > new file mode 100644
> > index 0000000000..73ad23c501
> > --- /dev/null
> > +++ b/python/qemu/machine/README.rst
> > @@ -0,0 +1,9 @@
> > +qemu.machine Package
> > +====================
> > +
> > +This package provides core utilities used for testing and debugging
> > +QEMU. It is used by the iotests, vm tests, and several other utilities
> > +in the ./scripts directory. It is not a fully-fledged SDK and it is
> > +subject to change at any time.
> > +
>
> I'm not sure if you intend to list all test types that use this, but
> the acceptance tests also do use them.

Wasn't a conscious omission, but didn't necessarily mean to make it 
comprehensive; I can add it while fixing the above feedback item too.

> - Cleber.

Thanks!