Description/Author formatting in tutorials/pyproject-toml.md

Author: lwasser

tutorials/pyproject-toml.md

@@ -170,27 +170,50 @@ Add the following to your table:
 - package **authors**
 - package **maintainers**
 
-When you add authors and maintainers you need to use a format that will look like a Python list with a dictionary within it:
+The `description` is just a string like the other values you've set:
+
+```toml
+# you can use """ for multiline strings like in python!
 
-`authors = [{ name = "Firstname lastname", email = "[email protected]" }]`
+description = """
+Tools that update the pyOpenSci contributor and review metadata
+that is posted on our website
+"""
+```
 
-If you have two authors you can add them like this:
+When you add authors and maintainers you need to use a format that will look like a Python list with a dictionary within it:
+
+```toml
+authors = [
+  { name = "Firstname Lastname", email = "[email protected]"},
+  { name = "Secondperson Fullname", email = "[email protected]" }
+]
 
-`authors = [{ name = "Firstname lastname", email = "[email protected]" }, { name = "Firstname lastname", email = "[email protected]" }]`
+maintainers = [
+  { name = "Secondperson Fullname", email = "[email protected]" },
+  { name = "New Friend", email = "[email protected]" }
+]
+```
 
 :::{admonition} Author names & emails
 :class: note
 
 There is a quirk with PyPI for authors that have names but not emails in the pyproject.toml. If you are missing the email for one or more authors or maintainers, like this:
 
 ```toml
-maintainers = [{ name = "Firstname lastname", email = "[email protected]" }, { name = "Firstname lastname" }]
+maintainers = [
+    { name = "Firstname lastname", email = "[email protected]" },
+    { name = "Firstname lastname" }
+]
 ```
 
 Then we suggest that you only provide names in your list of names to ensure that everything renders properly on your PyPI page - like this:
 
 ```toml
-maintainers = [{ name = "Firstname lastname"}, { name = "Firstname lastname" }]
+maintainers = [
+    { name = "Firstname lastname"},
+    { name = "Firstname lastname" }
+]
 ```
 
 don't have emails for everyone, we suggest that you only add names.
@@ -199,7 +222,7 @@ don't have emails for everyone, we suggest that you only add names.
 
 Your `pyproject.toml` file now should look like the example below. It is OK if you only have 1 author and the same author is also maintainer of your package:
 
-{emphasize-lines="8-10"}
+{emphasize-lines="8-19"}
 ```toml
 [build-system]
 requires = ["hatchling"]
@@ -208,9 +231,18 @@ build-backend = "hatchling.build"
 [project]
 name = "pyospackage"
 version = "0.1.0"
-description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
-authors = [{ name = "Firstname lastname", email = "[email protected]" }]
-maintainers = [{ name = "Firstname lastname", email = "[email protected]" }, { name = "Firstname lastname", email = "[email protected]" }]
+description = """
+Tools that update the pyOpenSci contributor and review metadata
+that is posted on our website
+"""
+authors = [
+  { name = "Firstname Lastname", email = "[email protected]"},
+  { name = "Secondperson Fullname", email = "[email protected]" }
+]
+maintainers = [
+  { name = "Secondperson Fullname", email = "[email protected]" },
+  { name = "New Friend", email = "[email protected]" }
+]
 ```
 
 :::{dropdown} Learn More: What's the difference between author and maintainer in open source?
@@ -238,7 +270,7 @@ In the previous lessons, you added both a [README.md](add-readme) file and a [LI
 Once you have those files, you can add them to your pyproject.toml file as
 links following the example below.
 
-{emphasize-lines="11-12"}
+{emphasize-lines="20-21"}
 ```toml
 [build-system]
 requires = ["hatchling"]
@@ -247,18 +279,27 @@ build-backend = "hatchling.build"
 [project]
 name = "pyospackage"
 version = "0.1.0"
-description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
-authors = [{ name = "Firstname lastname", email = "[email protected]" }]
-maintainers = [{ name = "Firstname lastname", email = "[email protected]" }, { name = "Firstname lastname", email = "[email protected]" }]
+description = """
+Tools that update the pyOpenSci contributor and review metadata
+that is posted on our website
+"""
+authors = [
+  { name = "Firstname Lastname", email = "[email protected]"},
+  { name = "Secondperson Fullname", email = "[email protected]" }
+]
+maintainers = [
+  { name = "Secondperson Fullname", email = "[email protected]" },
+  { name = "New Friend", email = "[email protected]" }
+]
 readme = "README.md"
-license = {file = 'LICENSE'}
+license = {file = "LICENSE"}
 ```
 ### Step 3: Specify Python version with `requires-python`
 
 Finally, add the `requires-python` field to your `pyproject.toml` `[project]` table. The `requires-python` field, helps pip understand the lowest version of Python that you package supports when it's installed. It is thus a single value.
 
 
-{emphasize-lines="13"}
+{emphasize-lines="22"}
 ```toml
 [build-system]
 requires = ["hatchling"]
@@ -267,9 +308,18 @@ build-backend = "hatchling.build"
 [project]
 name = "pyospackage"
 version = "0.1.0"
-description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
-authors = [{ name = "Firstname lastname", email = "[email protected]" }]
-maintainers = [{ name = "Firstname lastname", email = "[email protected]" }, { name = "Firstname lastname", email = "[email protected]" }]
+description = """
+Tools that update the pyOpenSci contributor and review metadata
+that is posted on our website
+"""
+authors = [
+  { name = "Firstname Lastname", email = "[email protected]"},
+  { name = "Secondperson Fullname", email = "[email protected]" }
+]
+maintainers = [
+  { name = "Secondperson Fullname", email = "[email protected]" },
+  { name = "New Friend", email = "[email protected]" }
+]
 readme = "README.md"
 license = {file = 'LICENSE'}
 requires-python = ">=3.10"
@@ -287,7 +337,7 @@ requires = ["hatchling"] # this is an array (or list) of requirements
 dependencies are added in an array (similar to a Python list) structure.
 
 
-{emphasize-lines="15"}
+{emphasize-lines="24"}
 ```toml
 [build-system]
 requires = ["hatchling"]
@@ -296,9 +346,18 @@ build-backend = "hatchling.build"
 [project]
 name = "pyospackage"
 version = "0.1.0"
-description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
-authors = [{ name = "Firstname lastname", email = "[email protected]" }]
-maintainers = [{ name = "Firstname lastname", email = "[email protected]" }, { name = "Firstname lastname", email = "[email protected]" }]
+description = """
+Tools that update the pyOpenSci contributor and review metadata
+that is posted on our website
+"""
+authors = [
+  { name = "Firstname Lastname", email = "[email protected]"},
+  { name = "Secondperson Fullname", email = "[email protected]" }
+]
+maintainers = [
+  { name = "Secondperson Fullname", email = "[email protected]" },
+  { name = "New Friend", email = "[email protected]" }
+]
 readme = "README.md"
 license = {file = 'LICENSE'}
 requires-python = ">=3.10"
@@ -354,7 +413,7 @@ The classifier key should look something like the example below. A few notes:
 - Your classifier values might be different depending upon the license you have selected for your package, your intended audience, development status of your package and the Python versions that you support
 - You can add as many classifiers as you wish as long as you use the [designated PyPI classifier values](https://PyPI.org/classifiers/).
 
-{emphasize-lines="17-24"}
+{emphasize-lines="26-34"}
 ```toml
 [build-system]
 requires = ["hatchling"]
@@ -363,9 +422,18 @@ build-backend = "hatchling.build"
 [project]
 name = "pyospackage"
 version = "0.1.0"
-description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
-authors = [{ name = "Firstname lastname", email = "[email protected]" }]
-maintainers = [{ name = "Firstname lastname", email = "[email protected]" }, { name = "Firstname lastname", email = "[email protected]" }]
+description = """
+Tools that update the pyOpenSci contributor and review metadata
+that is posted on our website
+"""
+authors = [
+  { name = "Firstname Lastname", email = "[email protected]"},
+  { name = "Secondperson Fullname", email = "[email protected]" }
+]
+maintainers = [
+  { name = "Secondperson Fullname", email = "[email protected]" },
+  { name = "New Friend", email = "[email protected]" }
+]
 readme = "README.md"
 license = {file = 'LICENSE'}
 requires-python = ">=3.10"
@@ -379,7 +447,8 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",]
+    "Programming Language :: Python :: 3.11",
+]
 ```
 
 Note that while classifiers are not required in your `pyproject.toml` file, they will help users find your package. As such we strongly recommend that you add them.
@@ -394,7 +463,7 @@ Finally, add the project.urls table to your pyproject.toml file.
 - **Bug reports:** a link to your issues / discussions or wherever you want users to report bugs.
 - **Source:** the GitHub / GitLab link for your project.
 
-{emphasize-lines="27-30"}
+{emphasize-lines="36-39"}
 ```toml
 [build-system]
 requires = ["hatchling"]
@@ -403,9 +472,18 @@ build-backend = "hatchling.build"
 [project]
 name = "pyospackage"
 version = "0.1.0"
-description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
-authors = [{ name = "Firstname lastname", email = "[email protected]" }]
-maintainers = [{ name = "Firstname lastname", email = "[email protected]" }, { name = "Firstname lastname", email = "[email protected]" }]
+description = """
+Tools that update the pyOpenSci contributor and review metadata
+that is posted on our website
+"""
+authors = [
+  { name = "Firstname Lastname", email = "[email protected]"},
+  { name = "Secondperson Fullname", email = "[email protected]" }
+]
+maintainers = [
+  { name = "Secondperson Fullname", email = "[email protected]" },
+  { name = "New Friend", email = "[email protected]" }
+]
 readme = "README.md"
 license = {file = 'LICENSE'}
 requires-python = ">=3.10"
@@ -445,9 +523,18 @@ build-backend = "hatchling.build"
 [project]
 name = "pyospackage"
 version = "0.1.0"
-description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
-authors = [{ name = "Firstname lastname", email = "[email protected]" }]
-maintainers = [{ name = "Firstname lastname", email = "[email protected]" }, { name = "Firstname lastname", email = "[email protected]" }]
+description = """
+Tools that update the pyOpenSci contributor and review metadata
+that is posted on our website
+"""
+authors = [
+  { name = "Firstname Lastname", email = "[email protected]"},
+  { name = "Secondperson Fullname", email = "[email protected]" }
+]
+maintainers = [
+  { name = "Secondperson Fullname", email = "[email protected]" },
+  { name = "New Friend", email = "[email protected]" }
+]
 readme = "README.md"
 license = {file = 'LICENSE'}
 requires-python = ">=3.10"