update pyproject readme docs

docs/pyproject.md

@@ -106,14 +106,28 @@ 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 should be in either Markdown (.md) or reStructuredText (.rst)
+format. 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" # or "README.rst"
 ```
 
+```toml
+[tool.poetry]
+# ...
+readme = ["docs/README1.md", "docs/README2.md"]
+```
+
 ## homepage
 
 An URL to the website of the project. **Optional**