README.md: Fix Markdown format for linting and update it

Signed-off-by: Bernhard Kaindl <[email protected]>

Author: bernhardkaindl

README.md

@@ -1,10 +1,10 @@
+# Common XenServer/XCP-ng Python classes
+
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
 [![](https://img.shields.io/badge/python-2.7_%7C_3.6_%7C_3.7_%7C_3.8_%7C_3.9_%7C_3.10_%7C_3.11+-blue.svg)](https://www.python.org/downloads/)
 [![codecov](https://codecov.io/gh/xenserver/python-libs/branch/master/graph/badge.svg?token=6WKVLDXJFN)](https://codecov.io/gh/xenserver/python-libs)
 [![](https://img.shields.io/badge/License-BSD--2--Cause%20%26%20MIT-brightgreen)](https://github.com/xenserver/python-libs/blob/master/LICENSE)
 
-# Common XenServer/XCP-ng Python classes
-
 The `xcp` directory contains the Common XenServer and XCP-ng Python packages.
 They are intented for use in XenServer and XCP-ng Dom0 only and deal with logging,
 Hardware/PCI, networking, and other Dom0 tasks.
@@ -18,6 +18,8 @@ It depends on `six`, and on Python 2.7, also `configparser` and `pyliblzma`.
 
 ## Test-driven Development (TDD) Model
 
+Please see [CONTRIBUTING.md] for installing a local development environment.
+
 This package has CI which can be run locally but is also run in GitHub CI to ensure
 Test-driven development.
 
@@ -81,7 +83,7 @@ For the installation of the general development dependencies, visit [INSTALL.md]
 
 The list of `virtualenvs` configured in tox can be shown using this command: `tox -av`
 
-```yaml
+```ml
 $ tox -av
 default environments:
 py36-lint              -> Run in a py36 virtualenv: Run pylint and fail on warnings remaining on lines in the diff to master
@@ -114,17 +116,20 @@ The goal or final benefit would be to have it to ensure internal type correctnes
 and code quality but also to use static analysis to check the interoperability with
 the calling code.
 
-## Type annotations: Use Type comments for now!
+## Type annotations: Use Type comments for now
 
 Python2.7 can't support the type annotation syntax, but until all users are migrated,
 annotations in comments (type comments) can be used. They are supported by
 tools like `mypy` and `pyright` (VS Code):
 
-Quoting from https://stackoverflow.com/questions/53306458/python-3-type-hints-in-python-2:
+Quoting from <https://stackoverflow.com/questions/53306458/python-3-type-hints-in-python-2>:
 
 > Function annotations were introduced in [PEP 3107](https://www.python.org/dev/peps/pep-3107/) for Python 3.0. The usage of annotations as type hints was formalized in in [PEP 484](https://www.python.org/dev/peps/pep-0484/) for Python 3.5+.
 >
-> Any version before 3.0 then will not support the syntax you are using for type hints at all. However, PEP 484 [offers a workaround](https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code), which some editors may choose to honor. In your case, the hints would look like this:
+> Python < 3.0 does support the type hints syntax, but
+> [PEP 484](https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code)
+> introduces type comments that are equally supported and are otherwise ignored.
+  These type comments look like this:
 
 ```py
 def get_default_device(use_gpu=True):
@@ -170,30 +175,19 @@ xcp/xmlunwrap.py
 Completed in 0.604sec
 ```
 
-See https://github.com/xenserver/python-libs/pull/23 for the context of this example.
+See <https://github.com/xenserver/python-libs/pull/23> for the context of this example.
 
-## Special open TODOs:
+## Guidelines
 
 Charset encoding/string handling:
-See [README-Unicode.md](README-Unicode.md) for details:
-
-- What's more: When code is called from a xapi plugin (such as ACK), when such code
-  attempts to read text files like the `pciids` file, and there is a Unicode char
-  it int, and the locale is not set up to be UTF-8 (because xapi plugins are started
-  from xapi), the UTF-8 decoder has to be explicitly enabled for these files,
-  bese by adding `encoding="utf-8"` to the arguments of these specific `open()` calls,
-  to have valid Unicode text strings, e.g. `xcp.pci`, for regular text processing.
-- TODO: More to be opened for all remaining `open()` and `Popen()` users,
-  as well as ensuring that users of `urllib` are able to work with they bytes
-  it returns (there is no option to use text mode, data may be gzip-encoded!)
+See [README-Unicode.md](README-Unicode.md) for details on Unicode support.
 
 ## Users
 
-- https://github.com/xenserver/host-installer
-  - /opt/xensource/installer/ (has copies of `cpiofile.py`, `repository.py` (with `accessor.py`)
-- https://github.com/xcp-ng-rpms/host-upgrade-plugin ([koji](https://koji.xcp-ng.org/packageinfo?packageID=104)):
+- [host-installer](https://github.com/xenserver/host-installer)
+- [host-upgrade-plugin](https://github.com/xcp-ng-rpms/host-upgrade-plugin) ([koji](https://koji.xcp-ng.org/packageinfo?packageID=104)):
   - /etc/xapi.d/plugins/prepare_host_upgrade.py
-- https://github.com/xapi-project/xen-api (`xapi-core.rpm` and `xenopsd.rpm`)
+- [xapi](https://github.com/xapi-project/xen-api) (`xapi-core.rpm` and `xenopsd.rpm`)
   - /etc/xapi.d/extensions/pool_update.apply
   - /etc/xapi.d/extensions/pool_update.precheck
   - /etc/xapi.d/plugins/disk-space
@@ -206,16 +200,16 @@ See [README-Unicode.md](README-Unicode.md) for details:
 - xenserver-release-config/[xcp-ng-release-config](https://koji.xcp-ng.org/rpminfo?rpmID=10250)
   - /opt/xensource/libexec/fcoe_driver
   - /opt/xensource/libexec/xen-cmdline
-- https://github.com/xcp-ng-rpms/interface-rename:
+- <https://github.com/xcp-ng-rpms/interface-rename>
   - /etc/sysconfig/network-scripts/interface-rename.py
   - /opt/xensource/bin/interface-rename
 - pvsproxy (Proprietary)
   - /usr/libexec/xapi-storage-script/volume/org.xen.xapi.storage.tmpfs/memoryhelper.py
-- https://github.com/xenserver/linux-guest-loader (not installed by default anymore)
+- <https://github.com/xenserver/linux-guest-loader> (not installed by default anymore)
   - /opt/xensource/libexec/eliloader.py
-- https://github.com/xcp-ng-rpms/vcputune
+- <https://github.com/xcp-ng-rpms/vcputune>
   - /opt/xensource/bin/host-cpu-tune
-- The ACK xenapi plugin see: https://github.com/xenserver/python-libs/pull/21
+- The ACK xapi plugin. See: <https://github.com/xenserver/python-libs/pull/21>
 
 Verification: