-
-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #353 from duckinator/docs
Add documentation about configuring Bork.
- Loading branch information
Showing
3 changed files
with
172 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,137 @@ | ||
Configuration | ||
============= | ||
|
||
Bork is configured using pyproject.toml. | ||
|
||
Build System/Backend | ||
-------------------- | ||
|
||
You always need to specify the ``[build-system]`` table. This should be | ||
configured according to the build backend you're using. | ||
|
||
If you are not using Bork to create ZipApps, this should be the only configuration | ||
that Bork requires. The build system (aka "backend") you use will likely | ||
want at least ``project.name`` and ``project.version`` or equivalent. See | ||
"Recommended pyproject.toml Configuration" below. | ||
|
||
`Python Packaging User Guide: Writing your pyproject.toml`_ | ||
explains this well if you're using Hatchling, Setuptools, Flit, or PDM. | ||
The information for Hatchling and Setuptool are also included below. | ||
|
||
For Setuptools, this looks like: | ||
|
||
.. code-block:: | ||
[build-system] | ||
requires = ["setuptools >= 61", "wheel"] | ||
build-backend = "setuptools.build_meta" | ||
If you are working on an existing Setuptools project with ``setup.py`` or | ||
``setup.cfg``, creating a ``pyproject.toml`` file with those contents should | ||
be enough to start using Bork and other `PEP 517`_-compliant frontends. | ||
|
||
For Hatchling it looks like: | ||
|
||
.. code-block:: | ||
[build-system] | ||
requires = ["hatchling"] | ||
build-backend = "hatchling.build" | ||
Recommended pyproject.toml Configuration | ||
---------------------------------------- | ||
|
||
In addition to the ``[build-system]`` configuration, it is recommended to | ||
include at least ``project.name`` and ``project.version`` (or equivalent). | ||
Some systems (e.g. Poetry) require the values to be specified in a different way. | ||
|
||
If you wish to have these values defined in pyproject.toml directly, it | ||
will look like this: | ||
|
||
.. code-block:: | ||
[project] | ||
name = "some-project-name" | ||
version = "0.0.1" | ||
For more advanced configurations, check | ||
`Python Packaging User Guide: Writing your pyproject.toml`_ or open a | ||
`GitHub Discussion for Bork`_. | ||
|
||
|
||
ZipApps | ||
------- | ||
|
||
To have Bork build a ZipApp, you need the entire recommended configuration | ||
described above. | ||
|
||
You also need to: | ||
|
||
* enable ZipApp functionality | ||
* specify the main function/entrypoint. | ||
|
||
For `Emanate <https://github.com/duckinator/emanate>`_, which has the ZipApp | ||
call the `emanate.cli.main()` function, this looks like: | ||
|
||
.. code-block:: | ||
[tool.bork.zipapp] | ||
enabled = true | ||
main = "emanate.cli:main" | ||
Releasing to PyPi and GitHub | ||
---------------------------- | ||
|
||
Configuring the release process for Bork happens in the ``[tool.bork.release]`` | ||
table in ``pyproject.toml``. | ||
|
||
As an example, Bork releases itself on PyPi and GitHub, and uses this configuration: | ||
|
||
.. code-block:: | ||
[tool.bork.release] | ||
pypi = true | ||
github = true | ||
github_repository = "duckinator/bork" | ||
strip_zipapp_version = true | ||
Here's what each option does: | ||
|
||
* ``pypi``: If true, release to PyPi using the project name reported by the build system. | ||
* ``github``: If true, release to GitHub using the specified ``github_repository``. | ||
* ``github_repository``: The name of the GitHub repository to publish releases to. | ||
* ``strip_zipapp_version``: If true, remove the version number from the ZipApp name. | ||
|
||
Setting ``strip_zipapp_version`` to true is recommended, because it means the | ||
latest ZipApp is always available at the same URL. | ||
|
||
For Bork, this URL is: https://github.com/duckinator/bork/releases/latest/download/bork.pyz | ||
|
||
You can provide a template for GitHub Releases by providing a :doc:`github-release-template`. | ||
|
||
Aliases | ||
------- | ||
|
||
Aliases can be configured in the ``[tool.bork.aliases]`` section of ``pyproject.toml``. | ||
|
||
Each alias can be either a string (one command) or a list of strings (multiple | ||
commands, ran one at a time, stopping if any of them fail). | ||
|
||
An example configuration (if your code is in a directory named ``example-project``) | ||
might look something like this: | ||
|
||
.. code-block:: | ||
[tool.bork.aliases] | ||
lint = [ | ||
"pylint example-project tests", | ||
"mypy example-project", | ||
] | ||
test = "pytest --verbose" | ||
.. _Python Packaging User Guide\: Writing your pyproject.toml: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/ | ||
.. _GitHub Discussion for Bork: https://github.com/duckinator/bork/discussions | ||
.. _PEP 517: https://peps.python.org/pep-0517/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
GitHub Release Template | ||
----------------------- | ||
|
||
You can create a template for GitHub releases, named ``.github/BORK_RELEASE_TEMPLATE.md``. | ||
|
||
You can reference a few variables using the syntax ``{variable_name}``. | ||
|
||
The avialable variables, and what they contain, are: | ||
|
||
* ``project_name``: The project name, as specified by the build backend. | ||
* ``owner``: The part before the ``/`` in ``github_repository`` in the :doc:`config`. | ||
* ``repo``: The part after the ``/`` in ``github_repository`` in the :doc:`config`. | ||
* ``tag``: The tag created by the release. This is ``v`` followed by the version number. | ||
* ``changelog``: A generated changelog based on merged Pull Requests since the last release. | ||
|
||
An example template might look like: | ||
|
||
.. code-block:: | ||
{project_name} {tag} is now available! | ||
PyPI package: https://pypi.org/project/bork/{version}/ | ||
Docker image: https://hub.docker.com/r/duckinator/bork/ | ||
The ZipApp is available below, as bork.pyz. | ||
You can help {project_name} by supporting me on [Patreon](https://www.patreon.com/duckinator)! | ||
--- | ||
Changes: | ||
{changelog} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,6 +2,8 @@ | |
:maxdepth: 1 | ||
|
||
index | ||
config | ||
github-release-template | ||
api | ||
asset_manager | ||
builder | ||
|