Sfoglia il codice sorgente

update docs/

master
parent
commit
75c51b2f01
Firmato da: NiklasRosenstein <rosensteinniklas@gmail.com> ID Chiave GPG: 06D269B33D25F6C6
8 ha cambiato i file con 137 aggiunte e 134 eliminazioni
  1. +0
    -122
      README.md
  2. +31
    -0
      docs/docs/configuration.md
  3. +57
    -0
      docs/docs/index.md
  4. +45
    -0
      docs/docs/package-data.md
  5. +0
    -0
      docs/docs/publishing-guide.md
  6. +2
    -0
      docs/mkdocs.yml
  7. +0
    -12
      docs/releasing.md
  8. +2
    -0
      docs/requirements.txt

+ 0
- 122
README.md Vedi File

@@ -6,128 +6,6 @@ Shore is an opinionated distribution and release management tool for pure
Python packages and mono repositories and is most effectively used with Git
repositories.

__Goals of Shore__

* Automate as much as possible of the release and distribution of Python
packages
* Prevent common mistakes from the beginning or provide tools to make it
easier to catch them
* Provide tooling for to handle Python package mono repositories

## Getting Started

__Installation__

Shore can be installed from PyPI.

$ pip install nr.shore
$ shore --version

__Configuring a Python package__

Shore reads all configuration for your package from its `package.yaml` file.
The `shore new` command can help you to initialize such a file. Alternatively,
check out the [`src/shore/model.py`](src/shore/model.py) source code to find
the fields available for the `package.yaml` file.

$ shore new mypackage . --license MIT

This command will also create a `LICENSE.txt` file as well as an initial
structure for your Python module if the files don't exist (ie.
`src/mypackage/__init__.py`). Note that if your module name differs from the
package name, you can specify the `--modulename <name>` option.

__Checking for misconfiguration__

Shore implements some automated checks to test the integrity of the data
in `package.yaml` with other files in the repository. Checks will be run on
`shore update` automatically, but for build automation they can also
be run separately. For CI checks, it's useful to turn on the
`--treat-warnings-as-errors` option which will cause the command to return a
non-zero status code if at least one warning is generated.

$ shore checks --treat-warnings-as-errors

__Rendering setup files__

Shore generates setup file from the data defined in `package.yaml`. We
recommend that these generated files are commited to the version control
system of choice to ensure that users of your project do not need to depend
on shore to install your package.

$ shore update

__Bumping the version number__

To bump the version number of your package at the same time, simply add the
`--version X.Y.Z` option add the specify `--patch`, `--minor` or `--major`
flags. Note that this will also update the version number in any files that
shore knows also contain the version number (eg. the entrypoin source file of
your package that contains the `__version__` variable).

$ shore bump minor --tag

__Publishing your package__

After the setup files have been generated, you can use the package manager
to build and publish your package. Shore can do the same for you if you don't
want to leave your comfort zone however. ;-)

Currently shore only supports the `pypi` publishing target, which by default
publishes your package on `https://pypi.org` (or `https://test.pypi.org` if
you add the `--test` flag).

$ shore publish pypi --test

> Note: If you explicityl specify the `use` section in `package.yaml`, you
> need to ensure that the `setuptools` and `pypi` plugin is in that list.

__Including package data__

There are two methods in which additional files can be shipped alongside a
Python package: "data files" and "package data". While files from the former
will be copied into a folder relative to `sys.prefix`, files from the latter
will be installed alongside the package and should be accessed with the
`pkg_resources` module.

Using "data files" usually requires some more effort to make it work with an
editable installation of your package during development (detecting that your
package is currently installed in editable mode and looking for the files in
a different location), thus using "package data" is usually the preferred
method. However if your additional files contain binaries that need to be
present on the file system, "data files" is the better bet.

"Data files" are configured with a special option called `datafiles` which
consists of alist of strings that define which files are to be copied to
what location inside `sys.prefix` as well as patterns for the files to copy.
The syntax is `<src>[:<dst>],<pattern>,<pattern>...`.

```yaml
datafiles:
- src/datafiles,file.txt
- src/datafiles:data,!file.txt
```

> Data files are always prefixed with `data/<packagename>`, thus to access the
> file at runtime you must add that to the path like this:
>
> ```py
> os.path.join(sys.prefix, 'data', 'mypackage', 'file.txt')
> ```

"Package files" on the other hand can be included by simply specifying them
in the `MANIFEST.in` file.

```yaml
manifest:
- include src/mypackage/data/file.txt
- recursive-include src/mypackage/data/models *.bin
```

> Tip: You can use the `shore build` command to produce a distribution archive
> of your package, which you can inspect to ensure the (package) data files
> are included as expected.

---

<p align="center">Copyright &copy; 2020, Niklas Rosenstein</p>

+ 31
- 0
docs/docs/configuration.md Vedi File

@@ -0,0 +1,31 @@
# Configuration

## Python Packages

Python packages are configured with a `package.yaml` file. Most of the information will be
rendered into the `setup.py` file when running the `shore update` command.

```yaml
name: my-package
version: 0.1.0
description: This is my package.
license: MIT
author: Me <me@me.org>
requirements:
- python ^2.7|^3.4 # Indicates that the package is universal
- click ~7.1.1
entrypoints:
console_scripts:
- my-cli = my_package.__main__:cli
```

## Mono Repositories

Monorepositories are configured with a `monorepo.yaml` file. Packages in the repository must be
in folder directly next to the configuration file.

```yaml
name: my-monorepo
version: null # Only needed for mono-versioning
mono-versioning: false
```

+ 57
- 0
docs/docs/index.md Vedi File

@@ -0,0 +1,57 @@
# Welcome to the Shore documentation

Shore is an opinionated release management tool for pure Python packages and mono repositories
of such. Among it's features is the automatic generation of setuptools files, sanity checks,
version number bumping and release publishing as well as changelog management.

## Installation

Shore can be installed from PyPI:

$ pip install nr.shore

## Typical Usage

Initialize a new Python package:

$ shore new my.package .
Write .gitignore
Write package.yaml
Write README.md
Write src/my/__init__.py
Write src/my/package/__init__.py
Write src/test/my/__init__.py
Write src/test/my/package/__init__.py
Write src/test/my/package/test_some.py

Generate setuptools files:

$ shore update
❌ 2 check(s) triggered
WARNING (my.package): missing $.url
WARNING (my.package): No LICENSE file found.
⚪ rendering 1 file(s)
setup.py

Release the initial version:

$ shore bump 0.0.1 --force --tag --push --publish pypi
bumping 2 version reference(s)
package.yaml: 0.0.1 → 0.0.1
src/my/package/__init__.py: 0.0.1 → 0.0.1
tagging 0.0.1
[master f0dd374] (my.package) bump version to 0.0.1
...

Create a changelog entry:

$ shore changelog --add feature --for cli -m 'Added some useful options.'

Release the next version:

$ shore bump --minor --tag --push --publish pypi

Shore also makes it easy to publish from within CI jobs. For more information on this,
check out the [Publishing Guide][0].

[0]: publishing-guide.md

+ 45
- 0
docs/docs/package-data.md Vedi File

@@ -0,0 +1,45 @@
# Package Data

There are two methods in which additional files can be shipped alongside a
Python package: "data files" and "package data". While files from the former
will be copied into a folder relative to `sys.prefix`, files from the latter
will be installed alongside the package and should be accessed with the
`pkg_resources` module.

Using "data files" usually requires some more effort to make it work with an
editable installation of your package during development (detecting that your
package is currently installed in editable mode and looking for the files in
a different location), thus using "package data" is usually the preferred
method. However if your additional files contain binaries that need to be
present on the file system, "data files" is the better bet.

"Data files" are configured with a special option called `datafiles` which
consists of alist of strings that define which files are to be copied to
what location inside `sys.prefix` as well as patterns for the files to copy.
The syntax is `<src>[:<dst>],<pattern>,<pattern>...`.

```yaml
datafiles:
- src/datafiles,file.txt
- src/datafiles:data,!file.txt
```

> Data files are always prefixed with `data/<packagename>`, thus to access the
> file at runtime you must add that to the path like this:
>
> ```py
> os.path.join(sys.prefix, 'data', 'mypackage', 'file.txt')
> ```

"Package files" on the other hand can be included by simply specifying them
in the `MANIFEST.in` file.

```yaml
manifest:
- include src/mypackage/data/file.txt
- recursive-include src/mypackage/data/models *.bin
```

> Tip: You can use the `shore build` command to produce a distribution archive
> of your package, which you can inspect to ensure the (package) data files
> are included as expected.

docs/publishing.md → docs/docs/publishing-guide.md Vedi File


+ 2
- 0
docs/mkdocs.yml Vedi File

@@ -0,0 +1,2 @@
site_name: Shore
theme: material

+ 0
- 12
docs/releasing.md Vedi File

@@ -1,12 +0,0 @@
# Releasing with Shore

Shore can automatically bump version numbers, tag push and publish a release in a single command.
The `<part>` can be an actual version number or one of `major`, `minor` and `patch`. See also
[Publishing with Shore](publishing.md).

$ shore bump <part> --tag --push --publish pypi

For initial releases (eg. `0.0.1`), the bump must be forced if the version you want to tag is
already the version number that is defined in `package.yaml`.

$ shore bump 0.0.1 --force --tag --push --publish pypi

+ 2
- 0
docs/requirements.txt Vedi File

@@ -0,0 +1,2 @@
mkdocs
mkdocs-material

Caricamento…
Annulla
Salva