📚 Add docs to the readme

Author: fwkoch

README.md

@@ -12,7 +12,106 @@ To use from the command line, use the `-g` to create a global install.
 npm install -g crossref-utils
 ```
 
-## From the command line
+## Creating a deposit
+
+To create a deposit, from within a [MyST](https://github.com/jupyter-book/mystmd) project, run:
+
+```
+crossref deposit --type <type> -o <output>.xml
+```
+
+This will prompt the user to select new DOIs, if they are not present in MyST metadata. Available options are:
+
+- `--type`: Currently available types are `journal`, `preprint`, `conference`, and `dataset`. Each type is discussed in more detail below.
+- `-o, --output`: Output xml file. If this is not provided, the xml will be printed to stdout.
+- `--file`: Specific file to use for the deposit; this may be a single article or a `myst.yml` file. If not specified, the CLI will prompt the user.
+- `--prefix`: DOI prefix to use for new, generated DOIs. Default is Curvenote's prefix.
+- `--name`, `--email`: Depositor name and email. Default Depositor is Curvenote.
+- `--registrant`: Registrant organization. Default is `Crossref` - likely this should not be changed.
+- `--id`: Unique ID for the deposit. By default, a random ID will be autogenerated - likely this should not be changed.
+
+### Deposit types
+
+Crossref supports multiple deposit types; currently `crossref-utils` supports the following four. For each of these, supported article metadata pulled from MyST frontmatter include:
+
+- `title`
+- `subtitle`
+- `doi`
+- `date` - used as publication date
+- `license` - only the URL is used
+- `funding` - MyST funding information is reduced to only award numbers and sources
+- `first_page`/`last_page`
+
+Additionally, the following information will be pulled from the MyST project:
+
+- `abstract`
+- `citations` - only citations with DOIs are included
+
+Different deposit types have different required fields. If DOIs are not provided, the user will be prompted to select new DOIs. If other required fields are not provided, the user will receive an error message.
+
+#### Journal
+
+This type is used to register a new journal and/or new journal articles. If `--file` is set to `myst.yml`, this deposit type will attempt to discover multiple articles in the MyST project.
+
+In addition to the above article metadata for each article, this deposit type requires journal title and DOI, set under `venue` frontmatter in `myst.yml`:
+
+- `venue.title` - journal title
+- `venue.doi` - journal DOI
+
+You may also specify in the frontmatter:
+
+- `venue.short_title` - journal abbreviation
+- `volume.number`
+- `issue.number`
+- `issue.doi`
+
+#### Conference
+
+This type is used to register a conference proceedings. Similar to "journal" deposits, this will attempt to discover multiple articles.
+
+In addition to the above article metadata for each article, this deposit type requires conference title, proceedings title, and proceedings publisher, set in `myst.yml` (Note - the mapping from available MyST frontmatter fields (venue/volume/journal) to required deposit fields (conference/proceedings/series) is currently complex and unintuitive, so be careful!):
+
+- `venue.title` - conference title
+- `volume.title` - proceedings title
+- `venue.publisher` - proceedings publisher
+
+You may also specify in the frontmatter:
+
+- `venue.short_title` - conference acronym
+- `venue.number` - conference number
+- `venue.date` - conference date
+- `venue.location` - conference location
+- `venue.series` - series title
+- `venue.issn` - series issn
+- `venue.doi` - series doi
+- `volume.subject` - proceedings subject
+- `editors` - proceedings editors
+
+#### Dataset
+
+This type is used to register a database deposit. For this type, each "article" is considered a dataset, where "article frontmatter" is used as dataset frontmatter.
+
+In addition to the individual dataset metadata, this deposit type requires a database title, set under `venue` frontmatter in `myst.yml`:
+
+- `venue.title` - database title
+
+You may also specify in the frontmatter:
+
+- `editors` - database contributors (independent from the individual dataset authors)
+- `venue.doi` - a related item that each dataset is part of.
+
+#### Preprint
+
+This type is used to register any posted content - these are standalone articles not associated with a journal or conference. You cannot register multiple articles with this type. Also, there is no additional metadata required than the article metadata described above.
+
+## Validating a deposit file
+
+To validate an existing deposit XML file against the schema:
+
+```
+crossref validate <deposit>.xml
+```
+
 
 ---