Skip to content

Commit 31ade2b

Browse files
author
Florian Maas
authored
improved documentation and readme (fpgmaas#15)
* improved documentation and readme
1 parent a43457e commit 31ade2b

19 files changed

+340
-276
lines changed

‎.vscode/settings.json

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"esbonio.sphinx.confDir": ""
3+
}

‎README.rst

+17-12
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,13 @@ Cookiecutter Poetry
3333

3434
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.
3535

36-
+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
37-
| **Github repository** | `https://github.com/fpgmaas/cookiecutter-poetry/ <https://github.com/fpgmaas/cookiecutter-poetry/>`_ |
38-
+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
39-
| **Documentation** | `https://fpgmaas.github.io/cookiecutter-poetry/ <https://fpgmaas.github.io/cookiecutter-poetry/>`_ |
40-
+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
36+
+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
37+
| **Github repository** | `https://github.com/fpgmaas/cookiecutter-poetry/ <https://github.com/fpgmaas/cookiecutter-poetry/>`_ |
38+
+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
39+
| **Documentation** | `https://fpgmaas.github.io/cookiecutter-poetry/ <https://fpgmaas.github.io/cookiecutter-poetry/>`_ |
40+
+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
41+
| **Example Repository** | `https://fpgmaas.github.io/cookiecutter-poetry-example/ <https://fpgmaas.github.io/cookiecutter-poetry-example/>`_ |
42+
+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
4143

4244

4345
Features
@@ -58,11 +60,11 @@ Features
5860
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
5961
| **CI/CD with Github actions** (Optional) | Adds Github actions that run the formatting checks and unittests for pull requests and when merged to `main`. |
6062
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
61-
| **Release to Pypi** (Optional) | Release to `Pypi <https://pypi.org>`_ manually, or by creating a new release on Github. |
63+
| **Release to Pypi** (Optional) | Release to `Pypi <https://pypi.org>`_ by creating a new release on Github. |
6264
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
63-
| **Release to Artifactory** (Optional) | Release to `Artifactory <https://jfrog.com/artifactory>`_ manually, or by creating a new release on Github. |
65+
| **Release to Artifactory** (Optional) | Release to `Artifactory <https://jfrog.com/artifactory>`_ by creating a new release on Github. |
6466
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
65-
| **Documentation with Sphinx** (Optional) | Automatically build documentation of your project and it's code with `Sphinx <https://www.sphinx-doc.org/>`_. |
67+
| **Documentation with Sphinx** (Optional) | Automatically add documentation to your project and its code with `Sphinx <https://www.sphinx-doc.org/>`_. |
6668
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
6769

6870
Quickstart
@@ -74,7 +76,7 @@ On your local machine, install ``cookiecutter`` with:
7476

7577
.. code-block:: bash
7678
77-
pip install -U cookiecutter
79+
pip install -U cookiecutter
7880
7981
Navigate to the directory in which you want to create your project and run:
8082

@@ -94,11 +96,14 @@ Run the following commands, replacing ``<project-name>``, with the name that you
9496
git push -u origin main
9597
9698
97-
Finally, install the environment with ``make install``.
99+
Finally, install the environment with ``make install``.
98100

101+
If you want to deploy to Pypi or Artifactory automatically on each release, you need to set
102+
some secrets in your repository on Github. For more information, see `the documentation <https://fpgmaas.github.io/cookiecutter-poetry/features/releasing.html>`_
99103

100-
Credits
101-
---------
104+
105+
Acknowledgements
106+
-----------------
102107

103108
This project is partially based on
104109
`Audrey Feldroy's <https://github.com/audreyfeldroy>`_'s great `cookiecutter-pypackage <https://github.com/audreyfeldroy/cookiecutter-pypackage>`_ repository.

‎docs/conf.py

+2
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,5 @@
5252
# a list of builtin themes.
5353
#
5454
html_theme = "sphinx_rtd_theme"
55+
56+
master_doc = "contents"

‎docs/contents.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. toctree::
2+
:maxdepth: 2
3+
4+
Cookiecutter Poetry <index>
5+
Tutorial <tutorial>
6+
Feature Details <feature_details>
7+
Prompt arguments <prompt_arguments>

‎docs/feature_details.rst

+11-129
Original file line numberDiff line numberDiff line change
@@ -2,132 +2,14 @@
22
Feature Details
33
====================
44

5-
6-
.. contents:: :local:
7-
:depth: 3
8-
9-
Poetry
10-
---------------
11-
12-
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.
13-
When you have created your repository using this cookiecutter template, a poetry environment is pre-configured in ``pyproject.toml`` and ``poetry.toml``. All you need to do is
14-
add your project-specific dependencies with
15-
16-
.. code-block:: bash
17-
18-
poetry add <package>
19-
20-
and then install the environment with
21-
22-
.. code-block:: bash
23-
24-
make install
25-
26-
By default, the environment is created in a `.venv` folder, so you can easily start a interactive shell within the environment with ``poetry shell``
27-
28-
Makefile
29-
-----------
30-
31-
A ``Makefile`` is available with the following commands:
32-
33-
+------------------------+-----------------------------------------------------------------------------------------------------------+
34-
| Command | Description |
35-
+========================+===========================================================================================================+
36-
| ``install`` | Install the poetry environment |
37-
+------------------------+-----------------------------------------------------------------------------------------------------------+
38-
| ``format`` | Format code using isort and black. |
39-
+------------------------+-----------------------------------------------------------------------------------------------------------+
40-
| ``lint`` | Check code formatting using isort, black, and flake8. |
41-
+------------------------+-----------------------------------------------------------------------------------------------------------+
42-
| ``test`` | Test the code with pytest |
43-
+------------------------+-----------------------------------------------------------------------------------------------------------+
44-
| ``build`` | Build wheel file using poetry |
45-
+------------------------+-----------------------------------------------------------------------------------------------------------+
46-
| ``clean-build`` | clean build artifacts |
47-
+------------------------+-----------------------------------------------------------------------------------------------------------+
48-
| ``publish`` | Available if ``publish_to`` is set to ``"pypi"`` or ``"artifactory"``. Publishes to the specified index. |
49-
+------------------------+-----------------------------------------------------------------------------------------------------------+
50-
| ``build-and-publish`` | Available if ``publish_to`` is set to ``"pypi"`` or ``"artifactory"``. Build and publish. |
51-
+------------------------+-----------------------------------------------------------------------------------------------------------+
52-
| ``docs-generate`` | Convert docstrings to ``rst``-files to prepare for building documentation with Sphinx. |
53-
+------------------------+-----------------------------------------------------------------------------------------------------------+
54-
| ``docs-build`` | Build documentation with sphinx. |
55-
+------------------------+-----------------------------------------------------------------------------------------------------------+
56-
| ``docs`` | Generate and build documentation with Sphinx, and directly open the documentation in the browser. |
57-
+------------------------+-----------------------------------------------------------------------------------------------------------+
58-
59-
Pytest
60-
----------
61-
62-
`pytest <https://docs.pytest.org/en/7.1.x/>`_ is automatically added to the environment, there is a template unittests in the ``tests`` directory and
63-
the tests can be run with
64-
65-
.. code-block:: bash
66-
67-
make test
68-
69-
70-
If ``include_github_actions`` is set to ``"y"``, the tests are automatically run for every merge request,
71-
every merge to main, and every release.
72-
73-
Formatting
74-
----------
75-
76-
`isort <https://pycqa.github.io/isort/index.html>`_, `black <https://pypi.org/project/black/>`_ and `flake8 <https://flake8.pycqa.org/en/latest/>`_ are added
77-
as development dependencies. ``black`` and ``isort`` can be used to format the code with
78-
79-
.. code-block:: bash
80-
81-
make format
82-
83-
All three packages can be used to verify the code formatting with
84-
85-
.. code-block:: bash
86-
87-
make lint
88-
89-
If ``include_github_actions`` is set to ``"y"``, code formatting is checked for every merge request, every merge to main, and every release.
90-
91-
Pyenv
92-
-------
93-
94-
A `.python-version` file is added with the specified ``python_version`` from the ``cookiecutter`` command, so that the right python version is used when ``make install`` is run.
95-
96-
CI/CD with Github actions (Optional)
97-
---------------------------------------
98-
99-
when ``include_github_actions`` is set to ``"y"``, a ``.github`` directory is added with the following structure:
100-
101-
::
102-
103-
.github
104-
├── workflows
105-
├─── run-checks
106-
│ └── action.yml
107-
├─── setup-poetry-env
108-
│ └── action.yml
109-
├── on-merge-to-main.yml
110-
├── on-pull-request.yml
111-
└── on-release-main.yml
112-
113-
``on-merge-to-main.yml`` and ``on-pull-request.tml`` are identical except for their trigger conditions; the first is run whenever a new commit is made to ``main``
114-
(which should only happen through merge requests, hence the name), and the latter is run whenever a pull request is opened or updated. They call the ``action.yml`` files
115-
to set-up the environment, run the tests, and check the code formatting.
116-
117-
``on-release-main.yml`` does all of the former whenever a new release is made on the ``main`` branch. To learn more about releasing,
118-
see :doc:`Releasing to Pypi or Artifactory <./releasing>`.
119-
120-
121-
Release to Pypi (Optional)
122-
----------------------------
123-
124-
See :doc:`Releasing to Pypi or Artifactory <./releasing>`
125-
126-
Release to Artifactory (Optional)
127-
----------------------------------
128-
129-
See :doc:`Releasing to Pypi or Artifactory <./releasing>`
130-
131-
Documentation with Sphinx (Optional)
132-
------------------------------------
133-
5+
.. toctree::
6+
:maxdepth: 2
7+
8+
features/poetry
9+
features/makefile
10+
features/pytest
11+
features/formatting
12+
features/pyenv
13+
features/cicd
14+
features/releasing
15+
features/sphinx

‎docs/features/cicd.rst

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
CI/CD with Github actions (Optional)
2+
---------------------------------------
3+
4+
when ``include_github_actions`` is set to ``"y"``, a ``.github`` directory is added with the following structure:
5+
6+
::
7+
8+
.github
9+
├── workflows
10+
├─── run-checks
11+
│ └── action.yml
12+
├─── setup-poetry-env
13+
│ └── action.yml
14+
├── on-merge-to-main.yml
15+
├── on-pull-request.yml
16+
└── on-release-main.yml
17+
18+
``on-merge-to-main.yml`` and ``on-pull-request.yml`` are identical except for their trigger conditions; the first is run
19+
whenever a new commit is made to ``main`` (which should `only
20+
<https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches>`_
21+
happen through merge requests, hence the name), and the latter is run whenever a pull request is opened or updated. They
22+
call the ``action.yml`` files to set-up the environment, run the tests, and check the code formatting.
23+
24+
``on-release-main.yml`` does all of the former whenever a new release is made on the ``main`` branch. In addition,
25+
``on-release-main.yml`` also publishes the project to Pypi or Artifactory if ``publish_to`` is set to ``"pypi"`` or
26+
``"artifactory"``, and it builds and deploys the documentation if ``sphinx_docs`` is set to ``"y"``. To learn more about
27+
these features, see :doc:`Releasing to Pypi or Artifactory <./releasing>` and :doc:`Documentation with Sphinx
28+
<./sphinx>`
29+
30+
31+

‎docs/features/formatting.rst

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
===============
2+
Formatting
3+
===============
4+
5+
`isort <https://pycqa.github.io/isort/index.html>`_, `black <https://pypi.org/project/black/>`_ and `flake8 <https://flake8.pycqa.org/en/latest/>`_ are added
6+
as development dependencies. ``black`` and ``isort`` can be used to format the code with
7+
8+
.. code-block:: bash
9+
10+
make format
11+
12+
All three packages can be used to verify the code formatting with
13+
14+
.. code-block:: bash
15+
16+
make lint
17+
18+
If ``include_github_actions`` is set to ``"y"``, code formatting is checked for every merge request, every merge to main, and every release.

‎docs/features/makefile.rst

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
============
2+
Makefile
3+
============
4+
5+
The generated repository will have a ``Makefile`` available. A list of all available commands that are available can be obtained by
6+
running ``make help`` in the terminal. Initially, the following commands are available:
7+
8+
+------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
9+
| Command | Description |
10+
+========================+============================================================================================================================================================+
11+
| ``install`` | Install the poetry environment |
12+
+------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
13+
| ``format`` | Format code using isort and black. |
14+
+------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
15+
| ``lint`` | Check code formatting using isort, black, and flake8. |
16+
+------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
17+
| ``test`` | Test the code with pytest |
18+
+------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
19+
| ``build`` | Build wheel file using poetry |
20+
+------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
21+
| ``clean-build`` | clean build artifacts |
22+
+------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
23+
| ``publish`` | Available if ``publish_to`` is set to ``"pypi"`` or ``"artifactory"``. Publishes to the specified index. |
24+
+------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
25+
| ``build-and-publish`` | Available if ``publish_to`` is set to ``"pypi"`` or ``"artifactory"``. Build and publish. |
26+
+------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
27+
| ``docs-generate`` | Available if ``sphinx_docs`` is set to ``"y"``. Convert docstrings to ``rst``-files to prepare for building documentation with Sphinx. |
28+
+------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
29+
| ``docs-build`` | Available if ``sphinx_docs`` is set to ``"y"``. Build documentation with sphinx. |
30+
+------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
31+
| ``docs`` | Available if ``sphinx_docs`` is set to ``"y"``. Generate and build documentation with Sphinx, and directly open the documentation in the browser. |
32+
+------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
33+

0 commit comments

Comments
 (0)