Initial commit and release of doi2dataset

docs/source/usage.rst

@@ -0,0 +1,77 @@
+Usage
+=====
+
+Running **doi2dataset** is done from the command line. Below is an example of how to use the tool.
+
+Basic Example
+-------------
+To process one or more DOIs, run:
+
+.. code-block:: bash
+
+   python doi2dataset.py 10.1234/doi1 10.5678/doi2
+
+Command Line Options
+--------------------
+The tool offers several command line options:
+
+- ``-f, --file``: Specify a file containing DOIs (one per line).
+- ``-o, --output-dir``: Directory where metadata files will be saved.
+- ``-d, --depositor``: Name of the depositor.
+- ``-s, --subject``: Default subject for the metadata.
+- ``-m, --contact-mail``: Contact email address.
+- ``-u, --upload``: Flag to upload metadata to a Dataverse server.
+
+Configuration via config.yaml
+-------------------------------
+Some options are also set via the **config.yaml** file. This file includes settings such as:
+
+- Dataverse connection details (URL, API token, authentication credentials).
+- Mapping of project phases.
+- PI (principal investigator) information.
+- Default grant configurations.
+
+Make sure that your **config.yaml** is properly configured before running the tool. For example, your **config.yaml** might include:
+
+.. code-block:: yaml
+
+   dataverse:
+     url: "https://your.dataverse.server"
+     api_token: "your_api_token"
+     auth_user: "your_username"
+     auth_password: "your_password"
+     dataverse: "your_dataverse_name"
+
+   phase:
+     Phase1:
+       start: 2010
+       end: 2015
+     Phase2:
+       start: 2016
+       end: 2020
+
+   pis:
+     - given_name: "John"
+       family_name: "Doe"
+       email: "john.doe@example.com"
+       orcid: "0000-0001-2345-6789"
+       affiliation: "Example University"
+       project:
+         - "Project A"
+         - "Project B"
+
+   default_grants:
+     - funder: "Funder Name"
+       id: "GrantID12345"
+
+Usage Example with Configuration
+----------------------------------
+If you have configured your **config.yaml** and want to process DOIs from a file while uploading the metadata, you could run:
+
+.. code-block:: bash
+
+   python doi2dataset.py -f dois.txt -o output/ -d "John Doe" -s "Medicine, Health and Life Sciences" -m "john.doe@example.com" -u
+
+This command will use the options provided on the command line as well as the settings from **config.yaml**.
+
+For more details on usage and configuration, please refer to the rest of the documentation.