update pyproject readme docs

docs/pyproject.md

@@ -106,12 +106,27 @@ maintainers = [
 
 ## readme
 
-The readme file of the package. **Optional**
+The path, or array of paths, to the readme file(s) of the package. **Optional**
 
-The file can be either `README.rst` or `README.md`.
+The file can be any format, but if you intend to publish to PyPI keep the
+[recommendations for a PyPI-friendly README](
+https://packaging.python.org/en/latest/guides/making-a-pypi-friendly-readme/)
+in mind. The path is relative to the directory containing the `pyproject.toml`.
+
+The file contents becomes the
+[Description field](https://packaging.python.org/en/latest/specifications/core-metadata/#description-optional)
+in a PyPI build (similar to `long_description` in setuptools). When specifying multiple readmes, their texts will be combined, separated by newlines.
+
+```toml
+[tool.poetry]
+# ...
+readme = "README.md"
+```
 
 ```toml
-readme = "README.md" # or "README.rst"
+[tool.poetry]
+# ...
+readme = ["docs/README1.md", "docs/README2.md"]
 ```
 
 ## homepage