[qemu.qmp,09/13,FIXME] move PACKAGE.rst to README.rst and update

The README here will reflect both what is shown on GitLab and on the
PyPI landing page. Update it accordingly, and freshen it up.

FIXME: Update URLs when pushing to the production repo.

Suggested-by: Kashyap Chamarthy <kchamart@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
---
 FILES.rst   |   2 +-
 MANIFEST.in |   2 +-
 PACKAGE.rst |  43 --------------
 README.rst  | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 setup.cfg   |   2 +-
 5 files changed, 163 insertions(+), 46 deletions(-)
 delete mode 100644 PACKAGE.rst
 create mode 100644 README.rst

On Wed, Mar 30, 2022 at 02:24:20PM -0400, John Snow wrote:
> The README here will reflect both what is shown on GitLab and on the
> PyPI landing page. Update it accordingly, and freshen it up.
> 
> FIXME: Update URLs when pushing to the production repo.
> 
> Suggested-by: Kashyap Chamarthy <kchamart@redhat.com>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---

Hi,

This version reads good to me. :)

[...]

> +
> +Who isn't this library for?
> +---------------------------
> +
> +It is not designed for anyone looking for a turn-key solution for VM
> +management. QEMU is a low-level component that resembles a particularly
> +impressive Swiss Army knife. This library does not manage that
> +complexity and is largely "VM-ignorant". It's not a replacement for
> +projects like `libvirt <https://libvirt.org/>`_, `virt-manager
> +<https://virt-manager.org/>`_, `GNOME Boxes
> +<https://wiki.gnome.org/Apps/Boxes>`_, etc.
> +
> +
> +Installing
> +----------
> +
> +This package can be installed from PyPI with pip: ``> pip3 install
> +qemu.qmp``.
> 
> +
> +Usage
> +-----
> +
> +Launch QEMU with a monitor, e.g.::
> +
> +  > qemu-system-x86_64 -qmp unix:qmp.sock,server=on,wait=off
> +
> +
> +Then, at its simplest, script-style usage looks like this::
> +
> +  import asyncio
> +  from qemu.qmp import QMPClient
> +
> +  async def main():
> +      qmp = QMPClient('my-vm-nickname')
> +      await qmp.connect('qmp.sock')
> +
> +      res = await qmp.execute('query-status')
> +      print(f"VM status: {res['status']}")
> +
> +      await qmp.disconnect()
> +
> +  asyncio.run(main())

Tested the exmaple; this works!

> +The above script will connect to the UNIX socket located at
> +``qmp.sock``, query the VM's runstate, then print it out
> +to the terminal::
> +
> +  > python3 example.py
> +  VM status: running
> +
> +
> +For more complex usages, especially those that make full advantage of
> +monitoring asynchronous events, refer to the `online documentation
> +<https://jsnow.gitlab.io/qemu.qmp/>`_ or type ``import qemu.qmp;
> +help(qemu.qmp)`` in your Python terminal of choice.
> +
> +
> +Contributing
> +------------
> +
> +Contributions are quite welcome! Please file bugs using the `GitLab
> +issue tracker <https://gitlab.com/jsnow/qemu.qmp/-/issues>`_. This
> +project will accept GitLab merge requests, but due to the close
> +association with the QEMU project, there are some additional guidelines:
> +
> +1. Please use the "Signed-off-by" tag in your commit messages. See
> +   https://wiki.linuxfoundation.org/dco for more information on this
> +   requirement.
> +
> +2. This repository won't squash merge requests into a single commit on
> +   pull; each commit should seek to be self-contained (within reason).
> +
> +3. Owing to the above, each commit sent as part of a merge request
> +   should not introduce any temporary regressions, even if fixed later
> +   in the same merge request. This is done to preserve bisectability.
> +
> +4. Please associate every merge request with at least one `GitLab issue
> +   <https://gitlab.com/jsnow/qemu.qmp/-/issues>`_. This helps with
> +   generating Changelog text and staying organized. Thank you 🙇

/me didn't miss the Japanese bow.

> +Developing
> +^^^^^^^^^^
> +
> +Optional packages necessary for running code quality analysis for this
> +package can be installed with the optional dependency group "devel":
> +``pip install qemu.qmp[devel]``.
> +
> +``make develop`` can be used to install this package in editable mode
> +(to the current environment) *and* bring in testing dependencies in one
> +command.
> +
> +``make check`` can be used to run the available tests. Consult ``make
> +help`` for other targets and tests that make sense for different
> +occasions.
> +
> +Before submitting a pull request, consider running ``make check-tox &&
> +make check-pipenv`` locally to spot any issues that will cause the CI to
> +fail. These checks use their own virtual environments and won't pollute
> +your working space.

Nit: Consider hyper-linking "virtual environments" to:
https://docs.python.org/3/library/venv.html#module-venv

(I realize, within context people will recognize the term "virtual
environment" is not a virtual guest environment, but a Python venv.  I
have a mild preference for being explicit here.)

FWIW:

Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com> 

[...]

On Fri, Apr 1, 2022, 12:40 PM Kashyap Chamarthy <kchamart@redhat.com> wrote:

> On Wed, Mar 30, 2022 at 02:24:20PM -0400, John Snow wrote:
> > The README here will reflect both what is shown on GitLab and on the
> > PyPI landing page. Update it accordingly, and freshen it up.
> >
> > FIXME: Update URLs when pushing to the production repo.
> >
> > Suggested-by: Kashyap Chamarthy <kchamart@redhat.com>
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
>
> Hi,
>
> This version reads good to me. :)
>
> [...]
>
> > +
> > +Who isn't this library for?
> > +---------------------------
> > +
> > +It is not designed for anyone looking for a turn-key solution for VM
> > +management. QEMU is a low-level component that resembles a particularly
> > +impressive Swiss Army knife. This library does not manage that
> > +complexity and is largely "VM-ignorant". It's not a replacement for
> > +projects like `libvirt <https://libvirt.org/>`_, `virt-manager
> > +<https://virt-manager.org/>`_, `GNOME Boxes
> > +<https://wiki.gnome.org/Apps/Boxes>`_, etc.
> > +
> > +
> > +Installing
> > +----------
> > +
> > +This package can be installed from PyPI with pip: ``> pip3 install
> > +qemu.qmp``.
> >
> > +
> > +Usage
> > +-----
> > +
> > +Launch QEMU with a monitor, e.g.::
> > +
> > +  > qemu-system-x86_64 -qmp unix:qmp.sock,server=on,wait=off
> > +
> > +
> > +Then, at its simplest, script-style usage looks like this::
> > +
> > +  import asyncio
> > +  from qemu.qmp import QMPClient
> > +
> > +  async def main():
> > +      qmp = QMPClient('my-vm-nickname')
> > +      await qmp.connect('qmp.sock')
> > +
> > +      res = await qmp.execute('query-status')
> > +      print(f"VM status: {res['status']}")
> > +
> > +      await qmp.disconnect()
> > +
> > +  asyncio.run(main())
>
> Tested the exmaple; this works!
>
> > +The above script will connect to the UNIX socket located at
> > +``qmp.sock``, query the VM's runstate, then print it out
> > +to the terminal::
> > +
> > +  > python3 example.py
> > +  VM status: running
> > +
> > +
> > +For more complex usages, especially those that make full advantage of
> > +monitoring asynchronous events, refer to the `online documentation
> > +<https://jsnow.gitlab.io/qemu.qmp/>`_ or type ``import qemu.qmp;
> > +help(qemu.qmp)`` in your Python terminal of choice.
> > +
> > +
> > +Contributing
> > +------------
> > +
> > +Contributions are quite welcome! Please file bugs using the `GitLab
> > +issue tracker <https://gitlab.com/jsnow/qemu.qmp/-/issues>`_. This
> > +project will accept GitLab merge requests, but due to the close
> > +association with the QEMU project, there are some additional guidelines:
> > +
> > +1. Please use the "Signed-off-by" tag in your commit messages. See
> > +   https://wiki.linuxfoundation.org/dco for more information on this
> > +   requirement.
> > +
> > +2. This repository won't squash merge requests into a single commit on
> > +   pull; each commit should seek to be self-contained (within reason).
> > +
> > +3. Owing to the above, each commit sent as part of a merge request
> > +   should not introduce any temporary regressions, even if fixed later
> > +   in the same merge request. This is done to preserve bisectability.
> > +
> > +4. Please associate every merge request with at least one `GitLab issue
> > +   <https://gitlab.com/jsnow/qemu.qmp/-/issues>`_. This helps with
> > +   generating Changelog text and staying organized. Thank you 🙇
>
> /me didn't miss the Japanese bow.
>
> > +Developing
> > +^^^^^^^^^^
> > +
> > +Optional packages necessary for running code quality analysis for this
> > +package can be installed with the optional dependency group "devel":
> > +``pip install qemu.qmp[devel]``.
> > +
> > +``make develop`` can be used to install this package in editable mode
> > +(to the current environment) *and* bring in testing dependencies in one
> > +command.
> > +
> > +``make check`` can be used to run the available tests. Consult ``make
> > +help`` for other targets and tests that make sense for different
> > +occasions.
> > +
> > +Before submitting a pull request, consider running ``make check-tox &&
> > +make check-pipenv`` locally to spot any issues that will cause the CI to
> > +fail. These checks use their own virtual environments and won't pollute
> > +your working space.
>
> Nit: Consider hyper-linking "virtual environments" to:
> https://docs.python.org/3/library/venv.html#module-venv
>
> (I realize, within context people will recognize the term "virtual
> environment" is not a virtual guest environment, but a Python venv.  I
> have a mild preference for being explicit here.)
>

OK. it's tough: there's a dual audience in mind here. People who are
familiar with Python development and QEMU devs who are not!

A link would suffice, but how to install, develop, and use python packages
can get a little complex. Longer than a paragraph, anyway.

Hard to know which complexities to omit and which to front-load.

¯\_(ツ)_/¯


> FWIW:
>
> Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com>


Thanks for your review prior to sending, and thanks for your re-review here
🙂


>
> [...]
>
>
> --
> /kashyap
>
>