diff --git a/README.md b/README.md new file mode 100644 index 0000000..d9be6cc --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +# Cookiecutter Poetry + +[![Release](https://img.shields.io/github/v/release/fpgmaas/cookiecutter-poetry)](https://pypi.org/project/cookiecutter-poetry/) +[![Build status](https://img.shields.io/github/workflow/status/fpgmaas/cookiecutter-poetry/merge-to-main)](https://img.shields.io/github/workflow/status/fpgmaas/cookiecutter-poetry/merge-to-main) +[![Supported Python versions](https://img.shields.io/pypi/pyversions/cookiecutter-poetry)](https://pypi.org/project/cookiecutter-poetry/) +[![Docs](https://img.shields.io/badge/docs-gh--pages-blue)](https://fpgmaas.github.io/cookiecutter-poetry/) +[![Commit activity](https://img.shields.io/github/commit-activity/m/fpgmaas/cookiecutter-poetry)](https://img.shields.io/github/commit-activity/m/fpgmaas/cookiecutter-poetry) +[![License](https://img.shields.io/github/license/fpgmaas/cookiecutter-poetry)](https://img.shields.io/github/license/fpgmaas/cookiecutter-poetry) + + +This is a [cookiecutter](https://github.com/cookiecutter/cookiecutter) +repository to generate the file structure for a Python project that uses +[Poetry](https://python-poetry.org/) for its dependency management. + +- **Documentation**: [Link](https://fpgmaas.github.io/cookiecutter-poetry/) +- **Example repository**: [Link](https://github.com/fpgmaas/cookiecutter-poetry-example) +- **PyPi**: [Link](https://pypi.org/project/cookiecutter-poetry/) + +## Features + +- [Poetry](https://python-poetry.org/), obviously. +- CI/CD with [GitHub Actions](https://github.com/features/actions) +- Formatting with [black](https://pypi.org/project/black/) and [isort](https://pycqa.github.io/isort/index.html) +- Publishing to [Pypi](https://pypi.org) or [Artifactory](https://jfrog.com/artifactory) by creating a new release on GitHub +- Testing with [pytest](https://docs.pytest.org/en/7.1.x/) +- Documentation with [MkDocs](https://www.mkdocs.org/) +- Compatibility testing for multiple versions of Python with [Tox](https://tox.wiki/en/latest/) + +## Example CI/CD Pipeline + +[![Example pipeline](https://raw.githubusercontent.com/fpgmaas/cookiecutter-poetry/main/static/images/pipeline.png)](https://raw.githubusercontent.com/fpgmaas/cookiecutter-poetry/main/static/images/pipeline.png) + +## Quickstart + +On your local machine, navigate to the directory in which you want to +create a project directory, and run the following two commands: + +``` bash +pip install cookiecutter-poetry +ccp +``` + +Alternatively, install `cookiecutter` and directly pass the URL to this +Github repository to the `cookiecutter` command: + +``` bash +pip install cookiecutter +cookiecutter https://github.com/fpgmaas/cookiecutter-poetry.git +``` + +Then run the following commands, replacing ``, with the +name that you also gave the Github repository and +`` with your Github username. + +``` bash +cd +git init -b main +git add . +git commit -m "Init commit" +git remote add origin git@github.com:/.git +git push -u origin main +``` + +Finally, install the environment with `make install`. + +You are now ready to start development on your project! The CI/CD +pipeline will be triggered when you open a pull request, merge to main, +or when you create a new release. + +To finalize the set-up for publishing to PyPi or Artifactory, see +[here](https://fpgmaas.github.io/cookiecutter-poetry/features/publishing/#set-up-for-pypi). +For activating the automatic documentation with MkDocs, see +[here](https://fpgmaas.github.io/cookiecutter-poetry/features/mkdocs/#enabling-the-documentation-on-github). + +## Acknowledgements + +This project is partially based on [Audrey +Feldroy\'s](https://github.com/audreyfeldroy)\'s great +[cookiecutter-pypackage](https://github.com/audreyfeldroy/cookiecutter-pypackage) +repository. diff --git a/README.rst b/README.rst deleted file mode 100644 index b7f4b7a..0000000 --- a/README.rst +++ /dev/null @@ -1,126 +0,0 @@ -==================== -Cookiecutter Poetry -==================== - -.. image:: https://img.shields.io/github/v/release/fpgmaas/cookiecutter-poetry - :target: https://pypi.org/project/cookiecutter-poetry/ - :alt: Release - -.. image:: https://img.shields.io/github/workflow/status/fpgmaas/cookiecutter-poetry/merge-to-main - :target: https://img.shields.io/github/workflow/status/fpgmaas/cookiecutter-poetry/merge-to-main - :alt: Build status - -.. image:: https://img.shields.io/pypi/pyversions/cookiecutter-poetry - :target: https://pypi.org/project/cookiecutter-poetry/ - :alt: Supported Python versions - -.. image:: https://img.shields.io/badge/docs-gh--pages-blue - :target: https://fpgmaas.github.io/cookiecutter-poetry/ - :alt: Docs - -.. image:: https://img.shields.io/github/commit-activity/m/fpgmaas/cookiecutter-poetry - :target: https://img.shields.io/github/commit-activity/m/fpgmaas/cookiecutter-poetry - :alt: Commit activity - -.. image:: https://img.shields.io/github/license/fpgmaas/cookiecutter-poetry - :target: https://img.shields.io/github/license/fpgmaas/cookiecutter-poetry - :alt: License - -.. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://github.com/psf/black - :alt: Code style with black - -.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1 - :target: https://pycqa.github.io/isort/ - :alt: Imports with isort - -This is a `cookiecutter `_ repository to generate the file structure for a Python project that uses `Poetry `_ for its dependency management. - -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ -| **Documentation** | `https://fpgmaas.github.io/cookiecutter-poetry/ `_ | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ -| **Example Repository** | `https://github.com/fpgmaas/cookiecutter-poetry-example/ `_ | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ -| **Pypi** | `https://pypi.org/project/cookiecutter-poetry/ `_ | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ - - -Features --------- - -+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Feature | Description | -+==============================================+============================================================================================================================================================+ -| **Poetry** | Generates a `poetry `_ environment file, ready to be installed with a single command. | -+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Makefile** | A makefile with pre-configured commands, type `make help` to list the options. | -+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Pytest** | Adds a `pytest `_ template. | -+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Formatting** | Adds code formatting with `isort `_ and `black `_. | -+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **CI/CD with Github actions** | Adds Github actions that run the formatting checks and unittests for pull requests and when merged to `main`. | -+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Release to Pypi** | Release to `Pypi `_ by creating a new release on Github. | -+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Release to Artifactory** | Release to `Artifactory `_ by creating a new release on Github. | -+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Documentation with MkDocs** | Automatically add documentation to your project and its code with `MkDocs `_. | -+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Tox testing** | Setup and CI/CD integration to easily test for different Python versions with `Tox `_. | -+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - -Example CI/CD Pipeline --------------------------- - -.. image:: https://raw.githubusercontent.com/fpgmaas/cookiecutter-poetry/main/static/images/pipeline.png - :target: https://raw.githubusercontent.com/fpgmaas/cookiecutter-poetry/main/static/images/pipeline.png - :alt: Example pipeline - -Quickstart ------------- - -On your local machine, navigate to the directory in which you want to create a project directory, and run the following two commands: - -.. code-block:: bash - - pip install cookiecutter-poetry - ccp - -Alternatively, install ``cookiecutter`` and directly pass the URL to this Github repository to the ``cookiecutter`` command: - -.. code-block:: bash - - pip install cookiecutter - cookiecutter https://github.com/fpgmaas/cookiecutter-poetry.git - -Then run the following commands, replacing ````, with the name that you also gave the Github repository and ```` with your Github username. - -.. code-block:: bash - - cd - git init -b main - git add . - git commit -m "Init commit" - git remote add origin git@github.com:/.git - git push -u origin main - - -Finally, install the environment with `make install`. - -You are now ready to start development on your project! The CI/CD pipeline will be triggered when you open a pull -request, merge to main, or when you create a new release. - -To finalize the set-up for publishing to PyPi or Artifactory through CI/CD, see `here `_. -For activating the automatic documentation with MkDocs, see `here `__. - - -Acknowledgements ------------------ - -This project is partially based on -`Audrey Feldroy's `_'s great `cookiecutter-pypackage `_ repository. - - - diff --git a/docs/index.md b/docs/index.md index 47e3c7b..b6bfa12 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,10 +15,10 @@ A project generated with ``cookiecutter-poetry`` supports the following features - [Poetry](https://python-poetry.org/), obviously. - CI/CD with [GitHub Actions](https://github.com/features/actions) - Formatting with [black](https://pypi.org/project/black/) and [isort](https://pycqa.github.io/isort/index.html) -- Publishing to [Pypi](https://pypi.org) or [Artifactory](https://jfrog.com/artifactory) by creating a new release on GitHub. +- Publishing to [Pypi](https://pypi.org) or [Artifactory](https://jfrog.com/artifactory) by creating a new release on GitHub - Testing with [pytest](https://docs.pytest.org/en/7.1.x/) - Documentation with [MkDocs](https://www.mkdocs.org/) -- Compatibility testing with [Tox](https://tox.wiki/en/latest/) +- Compatibility testing for multiple versions of Python with [Tox](https://tox.wiki/en/latest/) An example of a repository generated with this package can be found [here](https://github.com/fpgmaas/cookiecutter-poetry-example). @@ -57,7 +57,7 @@ Finally, install the environment with `make install`. You are now ready to start development on your project! The CI/CD pipeline will be triggered when you open a pull request, merge to main, or when you create a new release. -To finalize the set-up for publishing to PyPi or Artifactory through CI/CD, see [here](./features/publishing.md#set-up-for-pypi). For activating the automatic documentation with MkDocs, see [here](./features/mkdocs.md#enabling-the-documentation-on-github). +To finalize the set-up for publishing to PyPi or Artifactory, see [here](./features/publishing.md#set-up-for-pypi). For activating the automatic documentation with MkDocs, see [here](./features/mkdocs.md#enabling-the-documentation-on-github). ## Acknowledgements diff --git a/pyproject.toml b/pyproject.toml index 9f32d6d..e5d4363 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ description = "A python cookiecutter application to create a new python project authors = ["Florian Maas "] repository = "https://github.com/fpgmaas/cookiecutter-poetry" documentation = "https://fpgmaas.github.io/cookiecutter-poetry/" -readme = "README.rst" +readme = "README.md" keywords = ['cookiecutter', 'template', 'poetry'] packages = [ {include = "cookiecutter_poetry"}