Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
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 7b7dcca
Show file tree
Hide file tree
Showing 34 changed files with 71 additions and 1,651 deletions.
123 changes: 46 additions & 77 deletions 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 removed docs/assets/fonts/roboto-v19-latin-300.eot
Binary file not shown.

0 comments on commit 7b7dcca

Please sign in to comment.