gdcc · JR-1991 · Apr 12, 2024 · Apr 12, 2024 · Apr 12, 2024
diff --git a/.gitignore b/.gitignore
@@ -151,7 +151,6 @@ internal
 .python-version
 devel.py
 test_manual.py
-/docs
 src/pyDataverse/docs/build
 src/pyDataverse/docs/source/_build
 src/pyDataverse/docs/Makefile

diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,191 @@
+---
+hide:
+  - navigation
+---
+
+# PyDataverse
+
+[![PyPI](https://img.shields.io/pypi/v/pyDataverse.svg)](https://pypi.org/project/pyDataverse/) ![Build Status](https://github.com/gdcc/pyDataverse/actions/workflows/test_build.yml/badge.svg) [![GitHub](https://img.shields.io/github/license/gdcc/pydataverse.svg)](https://opensource.org/licenses/MIT) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4664557.svg)](https://doi.org/10.5281/zenodo.4664557)
+
+PyDataverse is an open source Python module for
+[Dataverse](http://dataverse.org). It helps to access the Dataverse [API's](http://guides.dataverse.org/en/latest/api/index.html) and manipulate, validate, import and export all Dataverse data-types (Dataverse, Dataset, Datafile).
+
+No matter, if you want to import huge masses of data into Dataverse,
+test your Dataverse instance after deployment or want to make basic API
+calls - _PyDataverse helps you with Dataverse!_
+
+## Features
+
+- Comprehensive API wrapper for all Dataverse API's and most of
+  their endpoints
+- Data models for each of Dataverses data types: Dataverse,
+  Dataset and Datafile
+- Data conversion to and from Dataverse's own JSON format for API
+  uploads
+- Easy mass imports and exports through CSV templates
+- Utils with helper functions
+- Documented examples and functionalities
+- Custom exceptions
+- Tested ([GitHub Actions](https://github.com/gdcc/pyDataverse/actions/workflows/test_build.yml)) and
+  documented ([MKdocs-Material](https://pydataverse.readthedocs.io/))
+- Open Source ([MIT](https://opensource.org/licenses/MIT))
+
+## Installation
+
+To install pyDataverse, simply run this command in your terminal of
+choice:
+
+```shell
+pip install pyDataverse
+```
+
+Find more options at `user_installation`{.interpreted-text role="ref"}.
+
+### Requirements
+
+Python packages required:
+
+- [httpx](https://www.python-httpx.org)\>=0.26.0
+- [jsonschema](https://github.com/Julian/jsonschema)\>=3.2.0
+
+## Quickstart
+
+!!! warning
+    Do not execute the example code on a Dataverse production instance, unless 100% sure!
+
+### Import Dataset metadata JSON
+
+To import the metadata of a Dataset from Dataverse's own JSON format, use `ds.from_json()`. The created `Dataset` can then be retrieved with the `get()` method.
+
+For this example, we use the `dataset.json` from
+`tests/data/user-guide/` ([GitHub
+repo](https://github.com/gdcc/pyDataverse/tree/master/tests/data/user-guide))
+and place it in the root directory.
+
+=== "Python"
+    ```python
+    from pyDataverse.models import Dataset
+    from pyDataverse.utils import read_file
+
+    ds = Dataset()
+    ds_filename = "dataset.json"
+    ds.from_json(read_file(ds_filename))
+    ds.get()
+    ```
+=== "Output"
+    ```python
+    {
+        'citation_displayName': 'Citation Metadata',
+        'title': 'Youth in Austria 2005',
+        'author': [
+            {
+                'authorName': 'LastAuthor1, FirstAuthor1',
+                'authorAffiliation': 'AuthorAffiliation1'
+            }
+        ],
+        'datasetContact': [
+            {
+                'datasetContactEmail': '[email protected]',
+                'datasetContactName': 'LastContact1, FirstContact1'
+            }
+        ],
+        'dsDescription': [
+            {
+                'dsDescriptionValue': 'DescriptionText'
+            }
+        ],
+        'subject': ['Medicine, Health and Life Sciences']
+    }
+    ```
+
+### Create Dataset by API
+
+To access Dataverse's Native API, you first have to instantiate `NativeApi`. Then create the Dataset through the API with `create_dataset()`.
+
+This returns, as all API functions do, a `httpx.Response` object, with the DOI inside `data`.
+
+Replace following variables with your own instance data before you execute the lines:
+
+- `BASE_URL`: Base URL of your Dataverse instance, without trailing slash (e. g. `https://data.aussda.at`))
+- `API_TOKEN`: API token of a Dataverse user with proper rights to create a Dataset
+- `DV_PARENT_ALIAS`: Alias of the Dataverse, the Dataset should be attached to.
+
+=== "Python"
+    ```python
+    from pyDataverse.api import NativeApi
+
+    api = NativeApi(BASE_URL, API_TOKEN)
+
+    response = api.create_dataset(DV_PARENT_ALIAS, ds.json())
+    response.raise_for_status() # Raise an exception if the request was unsuccessful
+
+    print(resp.json())
+    ```
+=== "Output"
+    ```bash
+    Dataset with pid 'doi:10.5072/FK2/UTGITX' created.
+
+    {
+        'status': 'OK',
+        'data': {
+            'id': 251,
+            'persistentId': 'doi:10.5072/FK2/UTGITX'
+        }
+    }
+    ```
+
+For more tutorials, check out
+`User Guide - Basic Usage <user_basic-usage>`{.interpreted-text
+role="ref"} and
+`User Guide - Advanced Usage <user_advanced-usage>`{.interpreted-text
+role="ref"}.
+
+## User Guide
+
+user/installation user/basic-usage user/advanced-usage user/use-cases
+user/csv-templates user/faq Wiki
+\<<https://github.com/gdcc/pyDataverse/wiki>\> user/resources
+:::
+
+## Reference / API
+
+If you are looking for information on a specific class, function, or
+method, this part of the documentation is for you.
+
+## Community Guide
+
+This part of the documentation, which is mostly prose, details the
+pyDataverse ecosystem and community.
+
+## Contributor Guide
+
+## Thanks!
+
+To everyone who has contributed to pyDataverse - with an idea, an issue,
+a pull request, developing used tools, sharing it with others or by any
+other means: **Thank you for your support!**
+
+Open Source projects live from the cooperation of the many and
+pyDataverse is no exception to that, so to say thank you is the least
+that can be done.
+
+Special thanks to Lars Kaczmirek, Veronika Heider, Christian Bischof,
+Iris Butzlaff and everyone else from AUSSDA, Slava Tykhonov and Marion
+Wittenberg from DANS and all the people who do an amazing job by
+developing Dataverse at IQSS, but especially to Phil Durbin for it\'s
+support from the first minute.
+
+pyDataverse is funded by [AUSSDA - The Austrian Social Science Data
+Archive](https://aussda.at) and through the EU Horizon2020 programme
+[SSHOC - Social Sciences & Humanities Open
+Cloud](https://www.sshopencloud.eu/about-sshoc) (T5.2).
+
+# License {#homepage_license}
+
+Copyright Stefan Kasberger and others, 2019-2021.
+
+Distributed under the terms of the MIT license, pyDataverse is free and
+open source software.
+
+Full License Text:
+[LICENSE.txt](https://github.com/GDCC/pyDataverse/blob/master/LICENSE.txt)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,55 @@
+site_name: PyDataverse
+repo_url: https://github.com/gdcc/pyDataverse
+edit_uri: edit/master/docs/
+theme:
+  font:
+    text: Open Sans
+  icon:
+    repo: fontawesome/brands/github
+    edit: material/pencil
+    view: material/eye
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.path
+    - navigation.top
+    - navigation.tracking
+    - toc.follow
+    - search.suggest
+    - content.action.edit
+    - content.code.copy
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      primary: pink
+      scheme: default
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      primary: pink
+      scheme: slate
+      toggle:
+        icon: material/weather-night
+        name: Switch to light mode
+nav:
+  - Home: index.md
+  - Code Reference: reference/
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+plugins:
+  - search
+  - gen-files:
+      scripts:
+        - scripts/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [src]
diff --git a/...ocs/source/_images/collection_dataset.png → ...ocs/source/_images/collection_dataset.png b/...ocs/source/_images/collection_dataset.png → ...ocs/source/_images/collection_dataset.png
diff --git a/src/pyDataverse/docs/source/_static/.gitkeep → old_docs/docs/source/_static/.gitkeep b/src/pyDataverse/docs/source/_static/.gitkeep → old_docs/docs/source/_static/.gitkeep
diff --git a/...averse/docs/source/_templates/layout.html → old_docs/docs/source/_templates/layout.html b/...averse/docs/source/_templates/layout.html → old_docs/docs/source/_templates/layout.html
diff --git a/...docs/source/_templates/sidebar_intro.html → ...docs/source/_templates/sidebar_intro.html b/...docs/source/_templates/sidebar_intro.html → ...docs/source/_templates/sidebar_intro.html
diff --git a/...rce/_templates/sidebar_related-links.html → ...rce/_templates/sidebar_related-links.html b/...rce/_templates/sidebar_related-links.html → ...rce/_templates/sidebar_related-links.html
diff --git a/...taverse/docs/source/community/contact.rst → old_docs/docs/source/community/contact.rst b/...taverse/docs/source/community/contact.rst → old_docs/docs/source/community/contact.rst
diff --git a/...averse/docs/source/community/releases.rst → old_docs/docs/source/community/releases.rst b/...averse/docs/source/community/releases.rst → old_docs/docs/source/community/releases.rst
diff --git a/src/pyDataverse/docs/source/conf.py → old_docs/docs/source/conf.py b/src/pyDataverse/docs/source/conf.py → old_docs/docs/source/conf.py
diff --git a/...docs/source/contributing/contributing.rst → ...docs/source/contributing/contributing.rst b/...docs/source/contributing/contributing.rst → ...docs/source/contributing/contributing.rst
diff --git a/src/pyDataverse/docs/source/index.rst → old_docs/docs/source/index.rst b/src/pyDataverse/docs/source/index.rst → old_docs/docs/source/index.rst
diff --git a/src/pyDataverse/docs/source/reference.rst → old_docs/docs/source/reference.rst b/src/pyDataverse/docs/source/reference.rst → old_docs/docs/source/reference.rst
diff --git a/...erse/docs/source/snippets/pip-install.rst → ...docs/docs/source/snippets/pip-install.rst b/...erse/docs/source/snippets/pip-install.rst → ...docs/docs/source/snippets/pip-install.rst
diff --git a/...rse/docs/source/snippets/requirements.rst → ...ocs/docs/source/snippets/requirements.rst b/...rse/docs/source/snippets/requirements.rst → ...ocs/docs/source/snippets/requirements.rst
diff --git a/...cs/source/snippets/warning_production.rst → ...cs/source/snippets/warning_production.rst b/...cs/source/snippets/warning_production.rst → ...cs/source/snippets/warning_production.rst
diff --git a/...verse/docs/source/user/advanced-usage.rst → old_docs/docs/source/user/advanced-usage.rst b/...verse/docs/source/user/advanced-usage.rst → old_docs/docs/source/user/advanced-usage.rst
diff --git a/...ataverse/docs/source/user/basic-usage.rst → old_docs/docs/source/user/basic-usage.rst b/...ataverse/docs/source/user/basic-usage.rst → old_docs/docs/source/user/basic-usage.rst
diff --git a/...averse/docs/source/user/csv-templates.rst → old_docs/docs/source/user/csv-templates.rst b/...averse/docs/source/user/csv-templates.rst → old_docs/docs/source/user/csv-templates.rst
diff --git a/src/pyDataverse/docs/source/user/faq.rst → old_docs/docs/source/user/faq.rst b/src/pyDataverse/docs/source/user/faq.rst → old_docs/docs/source/user/faq.rst
diff --git a/...taverse/docs/source/user/installation.rst → old_docs/docs/source/user/installation.rst b/...taverse/docs/source/user/installation.rst → old_docs/docs/source/user/installation.rst
diff --git a/...yDataverse/docs/source/user/resources.rst → old_docs/docs/source/user/resources.rst b/...yDataverse/docs/source/user/resources.rst → old_docs/docs/source/user/resources.rst
diff --git a/...yDataverse/docs/source/user/use-cases.rst → old_docs/docs/source/user/use-cases.rst b/...yDataverse/docs/source/user/use-cases.rst → old_docs/docs/source/user/use-cases.rst
diff --git a/requirements/docs.txt b/requirements/docs.txt
@@ -7,3 +7,9 @@ pydocstyle
 restructuredtext_lint
 pygments
 rstcheck
+
+# New deps for mkdocs
+mkdocs-material
+mkdocs-literate-nav
+mkdocstrings
+pymdown-extensions
diff --git a/scripts/gen_ref_pages.py b/scripts/gen_ref_pages.py
@@ -0,0 +1,33 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent
+src = root / "src"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        continue
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())