From 2e0bd8c01aaa2183db1bfe3bfeed07015d15f28d Mon Sep 17 00:00:00 2001 From: Jan Range Date: Fri, 12 Apr 2024 02:04:39 +0200 Subject: [PATCH 1/3] add mkdocs --- docs/index.md | 191 ++++++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 55 +++++++++++++++ 2 files changed, 246 insertions(+) create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..ac2f09e --- /dev/null +++ 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': 'ContactEmail1@mailinator.com', + '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 `{.interpreted-text +role="ref"} and +`User Guide - 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 +\<\> 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 new file mode 100644 index 0000000..9c9ddde --- /dev/null +++ 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] From 0d3f36a792a284df8db8ac850f1614b7b00e6e21 Mon Sep 17 00:00:00 2001 From: Jan Range Date: Fri, 12 Apr 2024 02:04:52 +0200 Subject: [PATCH 2/3] move old docs for now from `src` --- .../source/_images/collection_dataset.png | Bin .../docs/source/_static/.gitkeep | 0 .../docs/source/_templates/layout.html | 0 .../docs/source/_templates/sidebar_intro.html | 0 .../_templates/sidebar_related-links.html | 0 .../docs/source/community/contact.rst | 0 .../docs/source/community/releases.rst | 0 .../docs/source/conf.py | 0 .../docs/source/contributing/contributing.rst | 0 .../docs/source/index.rst | 0 .../docs/source/reference.rst | 0 .../docs/source/snippets/pip-install.rst | 0 .../docs/source/snippets/requirements.rst | 0 .../source/snippets/warning_production.rst | 0 .../docs/source/user/advanced-usage.rst | 0 .../docs/source/user/basic-usage.rst | 0 .../docs/source/user/csv-templates.rst | 0 .../docs/source/user/faq.rst | 0 .../docs/source/user/installation.rst | 0 .../docs/source/user/resources.rst | 0 .../docs/source/user/use-cases.rst | 0 requirements/docs.txt | 6 ++++ scripts/gen_ref_pages.py | 33 ++++++++++++++++++ 23 files changed, 39 insertions(+) rename {src/pyDataverse => old_docs}/docs/source/_images/collection_dataset.png (100%) rename {src/pyDataverse => old_docs}/docs/source/_static/.gitkeep (100%) rename {src/pyDataverse => old_docs}/docs/source/_templates/layout.html (100%) rename {src/pyDataverse => old_docs}/docs/source/_templates/sidebar_intro.html (100%) rename {src/pyDataverse => old_docs}/docs/source/_templates/sidebar_related-links.html (100%) rename {src/pyDataverse => old_docs}/docs/source/community/contact.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/community/releases.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/conf.py (100%) rename {src/pyDataverse => old_docs}/docs/source/contributing/contributing.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/index.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/reference.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/snippets/pip-install.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/snippets/requirements.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/snippets/warning_production.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/user/advanced-usage.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/user/basic-usage.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/user/csv-templates.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/user/faq.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/user/installation.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/user/resources.rst (100%) rename {src/pyDataverse => old_docs}/docs/source/user/use-cases.rst (100%) create mode 100644 scripts/gen_ref_pages.py diff --git a/src/pyDataverse/docs/source/_images/collection_dataset.png b/old_docs/docs/source/_images/collection_dataset.png similarity index 100% rename from src/pyDataverse/docs/source/_images/collection_dataset.png rename to old_docs/docs/source/_images/collection_dataset.png diff --git a/src/pyDataverse/docs/source/_static/.gitkeep b/old_docs/docs/source/_static/.gitkeep similarity index 100% rename from src/pyDataverse/docs/source/_static/.gitkeep rename to old_docs/docs/source/_static/.gitkeep diff --git a/src/pyDataverse/docs/source/_templates/layout.html b/old_docs/docs/source/_templates/layout.html similarity index 100% rename from src/pyDataverse/docs/source/_templates/layout.html rename to old_docs/docs/source/_templates/layout.html diff --git a/src/pyDataverse/docs/source/_templates/sidebar_intro.html b/old_docs/docs/source/_templates/sidebar_intro.html similarity index 100% rename from src/pyDataverse/docs/source/_templates/sidebar_intro.html rename to old_docs/docs/source/_templates/sidebar_intro.html diff --git a/src/pyDataverse/docs/source/_templates/sidebar_related-links.html b/old_docs/docs/source/_templates/sidebar_related-links.html similarity index 100% rename from src/pyDataverse/docs/source/_templates/sidebar_related-links.html rename to old_docs/docs/source/_templates/sidebar_related-links.html diff --git a/src/pyDataverse/docs/source/community/contact.rst b/old_docs/docs/source/community/contact.rst similarity index 100% rename from src/pyDataverse/docs/source/community/contact.rst rename to old_docs/docs/source/community/contact.rst diff --git a/src/pyDataverse/docs/source/community/releases.rst b/old_docs/docs/source/community/releases.rst similarity index 100% rename from src/pyDataverse/docs/source/community/releases.rst rename to old_docs/docs/source/community/releases.rst diff --git a/src/pyDataverse/docs/source/conf.py b/old_docs/docs/source/conf.py similarity index 100% rename from src/pyDataverse/docs/source/conf.py rename to old_docs/docs/source/conf.py diff --git a/src/pyDataverse/docs/source/contributing/contributing.rst b/old_docs/docs/source/contributing/contributing.rst similarity index 100% rename from src/pyDataverse/docs/source/contributing/contributing.rst rename to old_docs/docs/source/contributing/contributing.rst diff --git a/src/pyDataverse/docs/source/index.rst b/old_docs/docs/source/index.rst similarity index 100% rename from src/pyDataverse/docs/source/index.rst rename to old_docs/docs/source/index.rst diff --git a/src/pyDataverse/docs/source/reference.rst b/old_docs/docs/source/reference.rst similarity index 100% rename from src/pyDataverse/docs/source/reference.rst rename to old_docs/docs/source/reference.rst diff --git a/src/pyDataverse/docs/source/snippets/pip-install.rst b/old_docs/docs/source/snippets/pip-install.rst similarity index 100% rename from src/pyDataverse/docs/source/snippets/pip-install.rst rename to old_docs/docs/source/snippets/pip-install.rst diff --git a/src/pyDataverse/docs/source/snippets/requirements.rst b/old_docs/docs/source/snippets/requirements.rst similarity index 100% rename from src/pyDataverse/docs/source/snippets/requirements.rst rename to old_docs/docs/source/snippets/requirements.rst diff --git a/src/pyDataverse/docs/source/snippets/warning_production.rst b/old_docs/docs/source/snippets/warning_production.rst similarity index 100% rename from src/pyDataverse/docs/source/snippets/warning_production.rst rename to old_docs/docs/source/snippets/warning_production.rst diff --git a/src/pyDataverse/docs/source/user/advanced-usage.rst b/old_docs/docs/source/user/advanced-usage.rst similarity index 100% rename from src/pyDataverse/docs/source/user/advanced-usage.rst rename to old_docs/docs/source/user/advanced-usage.rst diff --git a/src/pyDataverse/docs/source/user/basic-usage.rst b/old_docs/docs/source/user/basic-usage.rst similarity index 100% rename from src/pyDataverse/docs/source/user/basic-usage.rst rename to old_docs/docs/source/user/basic-usage.rst diff --git a/src/pyDataverse/docs/source/user/csv-templates.rst b/old_docs/docs/source/user/csv-templates.rst similarity index 100% rename from src/pyDataverse/docs/source/user/csv-templates.rst rename to old_docs/docs/source/user/csv-templates.rst diff --git a/src/pyDataverse/docs/source/user/faq.rst b/old_docs/docs/source/user/faq.rst similarity index 100% rename from src/pyDataverse/docs/source/user/faq.rst rename to old_docs/docs/source/user/faq.rst diff --git a/src/pyDataverse/docs/source/user/installation.rst b/old_docs/docs/source/user/installation.rst similarity index 100% rename from src/pyDataverse/docs/source/user/installation.rst rename to old_docs/docs/source/user/installation.rst diff --git a/src/pyDataverse/docs/source/user/resources.rst b/old_docs/docs/source/user/resources.rst similarity index 100% rename from src/pyDataverse/docs/source/user/resources.rst rename to old_docs/docs/source/user/resources.rst diff --git a/src/pyDataverse/docs/source/user/use-cases.rst b/old_docs/docs/source/user/use-cases.rst similarity index 100% rename from src/pyDataverse/docs/source/user/use-cases.rst rename to old_docs/docs/source/user/use-cases.rst diff --git a/requirements/docs.txt b/requirements/docs.txt index 7b376cd..a1e0dd7 100644 --- 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 new file mode 100644 index 0000000..c60b2c1 --- /dev/null +++ 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()) From 4afe6c6bb668b4eef938f327a16c0137c2c57341 Mon Sep 17 00:00:00 2001 From: Jan Range Date: Fri, 12 Apr 2024 02:05:08 +0200 Subject: [PATCH 3/3] do not ignore `/docs` --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 5610c23..0d12339 100644 --- 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