Skip to content
Permalink
Browse files
docs: update readme after documentation update (DSP-1693) (#63)
* update readme with information for developers as in documentation

* cleanup docs directory

* add bash style to code blocks

* Update setup.py

* change documentation title

* correct typo

* redo change in setup.py as it is handled by the release bot

* correct typos
  • Loading branch information
irinaschubert committed Jun 8, 2021
1 parent 0294ec2 commit 7b7dcca55c729aa6bf995c04ae37f50a630bf9a5
Showing with 71 additions and 1,651 deletions.
  1. +46 −77 README.md
  2. BIN docs/assets/fonts/roboto-v19-latin-300.eot
  3. +0 −312 docs/assets/fonts/roboto-v19-latin-300.svg
  4. BIN docs/assets/fonts/roboto-v19-latin-300.ttf
  5. BIN docs/assets/fonts/roboto-v19-latin-300.woff
  6. BIN docs/assets/fonts/roboto-v19-latin-300.woff2
  7. BIN docs/assets/fonts/roboto-v19-latin-500.eot
  8. +0 −305 docs/assets/fonts/roboto-v19-latin-500.svg
  9. BIN docs/assets/fonts/roboto-v19-latin-500.ttf
  10. BIN docs/assets/fonts/roboto-v19-latin-500.woff
  11. BIN docs/assets/fonts/roboto-v19-latin-500.woff2
  12. BIN docs/assets/fonts/roboto-v19-latin-700.eot
  13. +0 −309 docs/assets/fonts/roboto-v19-latin-700.svg
  14. BIN docs/assets/fonts/roboto-v19-latin-700.ttf
  15. BIN docs/assets/fonts/roboto-v19-latin-700.woff
  16. BIN docs/assets/fonts/roboto-v19-latin-700.woff2
  17. BIN docs/assets/fonts/roboto-v19-latin-italic.eot
  18. +0 −323 docs/assets/fonts/roboto-v19-latin-italic.svg
  19. BIN docs/assets/fonts/roboto-v19-latin-italic.ttf
  20. BIN docs/assets/fonts/roboto-v19-latin-italic.woff
  21. BIN docs/assets/fonts/roboto-v19-latin-italic.woff2
  22. BIN docs/assets/fonts/roboto-v19-latin-regular.eot
  23. +0 −308 docs/assets/fonts/roboto-v19-latin-regular.svg
  24. BIN docs/assets/fonts/roboto-v19-latin-regular.ttf
  25. BIN docs/assets/fonts/roboto-v19-latin-regular.woff
  26. BIN docs/assets/fonts/roboto-v19-latin-regular.woff2
  27. BIN docs/{img.png → assets/images/img-list-example.png}
  28. BIN docs/assets/images/knora/knora-logo.png
  29. +14 −13 docs/dsp-tools-create.md
  30. +2 −0 docs/dsp-tools-information-for-developers.md
  31. +5 −2 docs/dsp-tools-usage.md
  32. BIN docs/img_1.png
  33. +2 −0 docs/index.md
  34. +2 −2 mkdocs.yml
123 README.md
@@ -1,131 +1,100 @@
[![PyPI version](https://badge.fury.io/py/dsp-tools.svg)](https://badge.fury.io/py/dsp-tools)

# DSP-TOOLS - The DaSCH Service Platform Tools Repository
dsp-tools is a python package containing a command line tool for data model (ontology) creation, a library allowing
creation of single resources and mass upload using the bulk import of data into the Knora framework.
# DSP-TOOLS - DaSCH Service Platform Tools

The package consists of:
- `dsplib` Python modules for accessing Knora using the API (ontology creation, data import/export etc.)
- `dsp-tools` A command line program to perfrom several operations on a DSP server:
- create an ontology out of a simple JSON description
- dump an existing ontology from a DSP server to a JSON file
- Bulk-upload of data from a XML data file
dsp-tools is a command line tool that helps you interact with the DaSCH Service Platform server (DSP server).

Go to [Full Documentation](https://dasch-swiss.github.io/dsp-tools/)

## Install
## Information for developers

_Please note that dsp-tools require Python 3.9 for working properly!_
There is a `Makefile` for all the following tasks (and more). Type `make` to print the available targets.

To install the latest published version from PyPI, run:
```
$ pip3 install dsp-tools
```
## Install from source

To upgrade to the latest published version, run:
```
$ pip3 install --upgrade dsp-tools
To install from source run:
```bash
python3 setup.py install
```

## Local Development Environment

- Python3
- [Bazel](https://bazel.build)
## Install the requirements

Please consult the [https://docs.dasch.swiss/developers](https://docs.dasch.swiss/developers)
documentation on how to install these prerequisites.
To install the requirements run:

## Makefile for repository management tasks
```bash
pip3 install -r requirements.txt
```

The project contains a Makefile defining management tasks. Please use
`make help` to see what is available.
To generate a requirements file (usually requirements.txt), that you commit with your project, run:

To install from source, i.e., this repository, run:
```
$ make install
```bash
pip3 freeze > requirements.txt
```

## Testing
Please note that testing requires launching the complete DSP API stack which is based on docker images. Therefore, we
recommend installing the [docker desktop client](https://www.docker.com/products).

To run the complete test suite:

```bash
$ make test
make test
```

## Publishing

Publishing is automated with github actions and should _not_ be done manually.

Ensure to have only one Pull Request per feature, and follow the [conventions for commit messages and PR title](https://docs.dasch.swiss/developers/dsp/contribution/#pull-request-guidelines).
Publishing is automated with GitHub Actions and should _not_ be done manually. Please follow the
[Pull Request Guidelines](https://docs.dasch.swiss/developers/dsp/contribution/#pull-request-guidelines). If done
correctly, when merging a pull request into `main`, the `release-please` action will create or update a pull request for
a release. This pull request will follow semantic versioning and update the change log. Once all desired features are
merged, the release can be executed by merging this release pull request into `main`. This will trigger actions that
create a release on GitHub, on PyPI and the docs.

If this is done correctly, when merging a PR into `main`, the `release-please` action will create or update a release-PR.
This PR will follow semantic versioning and update the change log.
Once all desired features are merged, the release can be executed by merging the release-PR into `main`.
This will trigger actions that create a release on Github, on PyPI and the docs.
Please ensure you have only one pull request per feature.

### Publishing to PyPi
## Publishing manually

Generate distribution package. Make sure you have the latest versions of `setuptools` and `wheel` installed.
Remove the `dist`and `buil`-directories: `rm -rf bild dist`
Publishing is automated with GitHub Actions and should _not_ be done manually. If you still need to do it, follow the
steps below.

Generate the distribution package. Make sure you have the latest versions of `setuptools` and `wheel` installed:

```bash
$ make upgrade-dist-tools
$ make dist
python3 -m pip install --upgrade pip setuptools wheel
python3 setup.py sdist bdist_wheel
```

You can install the package locally from the dist:

```bash
$ python3 -m pip install ./dist/some_name.whl
```

Upload package with `twine`,

first create `~/.pypirc` in your home folder:

```bash
[distutils]
index-servers=pypi
[pypi]
repository = https://upload.pypi.org/legacy/
username =your_username_on_pypi
python3 -m pip ./dist/some_name.whl
```

then upload:
Upload package works also with `make`:

```bash
$ make upload
make dist
make upload
```

For local development:

```bash
$ python3 setup.py --editable .
python3 setup.py develop
```

## Requirements

To install the requirements:

```bash
$ pip3 install -r requirements.txt
```
## Contributing to the documentation

To generate a "requirements" file (usually requirements.txt), that you commit with your project, do:
The documentation is a collection of [markdown](https://en.wikipedia.org/wiki/Markdown) files in the `docs` folder.
After updates of the files, build and check the result with the following commands:

```bash
$ pip3 freeze > requirements.txt
make build-docs
make serve-docs
```

### Running tests with Bazel

Run all tests:
```bash
$ bazel test //...
```
To update the changes to the official documentation pages run:

Run single test:
```bash
$ bazel test //test:test_user
make publish-docs
```

Binary file not shown.
Loading

0 comments on commit 7b7dcca

Please sign in to comment.