docs: 📝 move docs on Properties into docstrings and edit them (#991)

## Description

Cleaning up the interface docs by moving the text and example code of
the properties dataclass into the docstrings. Plus, did some small edits
for clarity.

<!-- Select quick/in-depth as necessary -->
This PR needs an in-depth review.

## Checklist

- [ ] Added or updated tests
- [x] Updated documentation
- [x] Ran `just run-all`

---------

Co-authored-by: martonvago <[email protected]>

docs/design/interface/python-functions.qmd

@@ -417,6 +417,38 @@ print(path_resource_data(4, 2))
 ```
 :::
 
+## Properties dataclasses
+
+These dataclasses contain an explicit, structured set of official
+properties defined within a data package. The main purpose of these is
+to allow us to pass structured properties objects between functions.
+They also enable users to create valid properties objects more easily
+and get an overview of optional and required class fields.
+
+::: {.callout-note collapse="true"}
+### `PackageProperties`
+
+See the help documentation with `help(PackageProperties())` for more
+details on the properties.
+:::
+
+## Properties functions
+
+::: {.callout-warning collapse="true"}
+### `read_properties(path)`
+
+Reads the `datapackage.json` file, checks that is correct, and then
+outputs a `PackageProperties` object.
+:::
+
+::: {.callout-warning collapse="true"}
+### `view_properties(path)`
+
+Reads the `datapackage.json` file, checks that is correct, and then
+outputs a human-readable version of the properties as a string.
+:::
+
+
 ::: {.callout-note collapse="true"}
 ### `path_properties(package_id)`
 
@@ -497,130 +529,6 @@ print(path_sprout_global())
 ```
 [PosixPath('~/.sprout')]
 ```
-:::
-
-## Properties dataclasses
-
-These dataclasses contain an explicit, structured set of official
-properties defined within a data package. The main purpose of these is
-to allow us to pass structured properties objects between functions.
-They also enable users to create valid properties objects more easily
-and get an overview of optional and required class fields.
-
-::: {.callout-note collapse="true"}
-### `PackageProperties(...)`
-
-Creates a dataclass object with all the necessary properties for the top
-level metadata of a data package.
-
-#### Example usage
-
-``` python
-print(PackageProperties())
-```
-
-<!-- TODO: This is only showing a subset for illustrating purposes, this output will be autogenerated later. -->
-
-```
-PackageProperties(title=None, description=None, licenses=None, contributors=None, resources=None)
-```
-
-``` python
-print(PackageProperties(title="Diabetes Cohort"))
-```
-
-```
-PackageProperties(title="Diabetes Cohort", description=None, licenses=None, contributors=None, resources=None)
-```
-
-``` python
-print(PackageProperties(licenses=[LicenseProperties(name="ODC-BY-1.0")]))
-```
-
-```
-PackageProperties(title=None, description=None, licenses=[LicenseProperties(name="ODC-BY-1.0")], contributors=None, resources=None)
-```
-:::
-
-::: {.callout-note collapse="true"}
-### `ResourceProperties(...)`
-
-Creates a dataclass object with all the necessary properties for a
-resource, which would be given in the `resources` field of a
-`PackageProperties` object.
-
-#### Example usage
-
-``` python
-print(ResourceProperties())
-```
-
-```
-ResourceProperties(name=None, description=None, path=None, schema=None)
-```
-
-``` python
-print(ResourceProperties(name="Blood Samples"))
-```
-
-```
-ResourceProperties(name="Blood Samples", description=None, path=None, schema=None)
-```
-:::
-
-::: {.callout-note collapse="true"}
-### `ContributorProperties(...)`
-
-Creates a dataclass object with all the necessary properties for a
-contributor. This would be given in the `contributors` field of a
-`PackageProperties` object.
-
-#### Example usage
-
-``` python
-print(ContributorProperties())
-```
-
-```
-ContributorProperties(title=None, email=None, roles=None)
-```
-:::
-
-::: {.callout-note collapse="true"}
-### `LicenseProperties(...)`
-
-Creates a dataclass object with all the necessary properties for a
-license, so that it can be added to the `licenses` field of a
-`PackageProperties` object.
-
-#### Example usage
-
-``` python
-print(LicenseProperties())
-```
-
-```
-LicenseProperties(name=None, path=None, title=None)
-```
-:::
-
-::: {.callout-note collapse="true"}
-### `TableSchemaProperties(...)`
-
-Creates a dataclass object with all the necessary properties for a table
-schema, so that it can be added to the `schema` field of a
-`ResourceProperties` object.
-
-#### Example usage
-
-``` python
-print(TableSchemaProperties())
-```
-
-```
-TableSchemaProperties(fields=[], missingValues=[], primaryKey=[], foreignKeys=[])
-```
-:::
 
 ## Helper functions