diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index e0372d2b5..000000000 --- a/.gitmodules +++ /dev/null @@ -1,3 +0,0 @@ -[submodule "docs/HelloCookieCutter1"] - path = docs/HelloCookieCutter1 - url = https://github.com/BruceEckel/HelloCookieCutter1 diff --git a/AUTHORS.md b/AUTHORS.md index fd75a6943..d63785240 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -169,6 +169,7 @@ - Tom Forbes ([@orf](https://github.com/orf)) - Xie Yanbo ([@xyb](https://github.com/xyb)) - Maxim Ivanov ([@ivanovmg](https://github.com/ivanovmg)) +- Jens Klein ([@jensens](https://github.com/jensens)) ## Backers diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 5b484056f..3043a6bab 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,5 +1,4 @@ # Code of Conduct -Everyone interacting in the Cookiecutter project's codebases, issue trackers, -chat rooms, and mailing lists is expected to follow the -[PyPA Code of Conduct](https://www.pypa.io/en/latest/code-of-conduct/). +Everyone interacting in the Cookiecutter project's codebases and documentation is expected to follow the [PyPA Code of Conduct](https://www.pypa.io/en/latest/code-of-conduct/). +This includes, but is not limited to, issue trackers, chat rooms, mailing lists, and other virtual or in real life communication. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f54ae0e06..f0ae0bb42 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,13 @@ # Contributing -Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. +Contributions are welcome, and they are greatly appreciated! +Every little bit helps, and credit will always be given. -* [Types of Contributions](#Types-of-Contributions) -* [Contributor Setup](#Setting-Up-the-Code-for-Local-Development) -* [Contributor Guidelines](#Contributor-Guidelines) -* [Contributor Testing](#Testing-with-tox) -* [Core Committer Guide](#Core-Committer-Guide) +- [Types of Contributions](#Types-of-Contributions) +- [Contributor Setup](#Setting-Up-the-Code-for-Local-Development) +- [Contributor Guidelines](#Contributor-Guidelines) +- [Contributor Testing](#Testing-with-tox) +- [Core Committer Guide](#Core-Committer-Guide) ## Types of Contributions @@ -18,22 +19,27 @@ Report bugs at [https://github.com/cookiecutter/cookiecutter/issues](https://git If you are reporting a bug, please include: -* Your operating system name and version. -* Any details about your local setup that might be helpful in troubleshooting. -* If you can, provide detailed steps to reproduce the bug. -* If you don't have steps to reproduce the bug, just note your observations in as much detail as you can. Questions to start a discussion about the issue are welcome. +- Your operating system name and version. +- Any details about your local setup that might be helpful in troubleshooting. +- If you can, provide detailed steps to reproduce the bug. +- If you don't have steps to reproduce the bug, just note your observations in as much detail as you can. + Questions to start a discussion about the issue are welcome. ### Fix Bugs -Look through the GitHub issues for bugs. Anything tagged with "bug" is open to whoever wants to implement it. +Look through the GitHub issues for bugs. +Anything tagged with "bug" is open to whoever wants to implement it. ### Implement Features -Look through the GitHub issues for features. Anything tagged with "enhancement" and "please-help" is open to whoever wants to implement it. +Look through the GitHub issues for features. +Anything tagged with "enhancement" and "please-help" is open to whoever wants to implement it. Please do not combine multiple feature enhancements into a single pull request. -Note: this project is very conservative, so new features that aren't tagged with "please-help" might not get into core. We're trying to keep the code base small, extensible, and streamlined. Whenever possible, it's best to try and implement feature ideas as separate projects outside of the core codebase. +Note: this project is very conservative, so new features that aren't tagged with "please-help" might not get into core. +We're trying to keep the code base small, extensible, and streamlined. +Whenever possible, it's best to try and implement feature ideas as separate projects outside of the core codebase. ### Write Documentation @@ -54,9 +60,9 @@ The best way to send feedback is to file an issue at [https://github.com/cookiec If you are proposing a feature: -* Explain in detail how it would work. -* Keep the scope as narrow as possible, to make it easier to implement. -* Remember that this is a volunteer-driven project, and that contributions are welcome :) +- Explain in detail how it would work. +- Keep the scope as narrow as possible, to make it easier to implement. +- Remember that this is a volunteer-driven project, and that contributions are welcome :) ## Setting Up the Code for Local Development @@ -65,56 +71,58 @@ Here's how to set up `cookiecutter` for local development. 1. Fork the `cookiecutter` repo on GitHub. 2. Clone your fork locally: -```bash -git clone git@github.com:your_name_here/cookiecutter.git -``` + ```bash + git clone git@github.com:your_name_here/cookiecutter.git + ``` -3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development: +3. Install your local copy into a virtualenv. + Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development: -```bash - -cd cookiecutter/ -pip install -e . -``` + ```bash + cd cookiecutter/ + pip install -e . + ``` 4. Create a branch for local development: -```bash -git checkout -b name-of-your-bugfix-or-feature -``` + ```bash + git checkout -b name-of-your-bugfix-or-feature + ``` Now you can make your changes locally. 5. When you're done making changes, check that your changes pass the tests and lint check: -```bash -pip install tox -tox -``` + ```bash + pip install tox + tox + ``` -Please note that tox runs lint check automatically, since we have a test environment for it. + Please note that tox runs lint check automatically, since we have a test environment for it. -If you feel like running only the lint environment, please use the following command: + If you feel like running only the lint environment, please use the following command: -```bash -make lint -``` + ```bash + make lint + ``` -6. Ensure that your feature or commit is fully covered by tests. Check report after regular tox run. You can also run coverage only report and get html report with statement by statement highlighting: +6. Ensure that your feature or commit is fully covered by tests. Check report after regular tox run. + You can also run coverage only report and get html report with statement by statement highlighting: -```bash -make coverage -``` + ```bash + make coverage + ``` -You report will be placed to `htmlcov` directory. Please do not include this directory to your commits. By default this directory in our `.gitignore` file. + You report will be placed to `htmlcov` directory. Please do not include this directory to your commits. + By default this directory in our `.gitignore` file. 7. Commit your changes and push your branch to GitHub: -```bash -git add . -git commit -m "Your detailed description of your changes." -git push origin name-of-your-bugfix-or-feature -``` + ```bash + git add . + git commit -m "Your detailed description of your changes." + git push origin name-of-your-bugfix-or-feature + ``` 8. Submit a pull request through the GitHub website. @@ -125,34 +133,36 @@ git push origin name-of-your-bugfix-or-feature Before you submit a pull request, check that it meets these guidelines: 1. The pull request should include tests. -2. The pull request should be contained: if it's too big consider splitting it into smaller pull requests. -3. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.md. +2. The pull request should be contained: + if it's too big consider splitting it into smaller pull requests. +3. If the pull request adds functionality, the docs should be updated. + Put your new functionality into a function with a docstring, and add the feature to the list in README.md. 4. The pull request must pass all CI/CD jobs before being ready for review. 5. If one CI/CD job is failing for unrelated reasons you may want to create another PR to fix that first. ### Coding Standards -* PEP8 -* Functions over classes except in tests -* Quotes via [http://stackoverflow.com/a/56190/5549](http://stackoverflow.com/a/56190/5549) - - * Use double quotes around strings that are used for interpolation or that are natural language messages - * Use single quotes for small symbol-like strings (but break the rules if the strings contain quotes) - * Use triple double quotes for docstrings and raw string literals for regular expressions even if they aren't needed. - * Example: - -```python -LIGHT_MESSAGES = { - 'English': "There are %(number_of_lights)s lights.", - 'Pirate': "Arr! Thar be %(number_of_lights)s lights." -} -def lights_message(language, number_of_lights): - """Return a language-appropriate string reporting the light count.""" - return LIGHT_MESSAGES[language] % locals() -def is_pirate(message): - """Return True if the given message sounds piratical.""" - return re.search(r"(?i)(arr|avast|yohoho)!", message) is not None -``` +- PEP8 +- Functions over classes except in tests +- Quotes via [http://stackoverflow.com/a/56190/5549](http://stackoverflow.com/a/56190/5549) + + - Use double quotes around strings that are used for interpolation or that are natural language messages + - Use single quotes for small symbol-like strings (but break the rules if the strings contain quotes) + - Use triple double quotes for docstrings and raw string literals for regular expressions even if they aren't needed. + - Example: + + ```python + LIGHT_MESSAGES = { + 'English': "There are %(number_of_lights)s lights.", + 'Pirate': "Arr! Thar be %(number_of_lights)s lights." + } + def lights_message(language, number_of_lights): + """Return a language-appropriate string reporting the light count.""" + return LIGHT_MESSAGES[language] % locals() + def is_pirate(message): + """Return True if the given message sounds piratical.""" + return re.search(r"(?i)(arr|avast|yohoho)!", message) is not None + ``` ## Testing with tox @@ -186,7 +196,8 @@ To run all tests using various versions of python in virtualenvs defined in tox. tox ``` -This configuration file setup the pytest-cov plugin and it is an additional dependency. It generate a coverage report after the tests. +This configuration file setup the pytest-cov plugin and it is an additional dependency. +It generate a coverage report after the tests. It is possible to test with specific versions of Python. To do this, the command is: @@ -202,93 +213,97 @@ This will run `py.test` with the `python3.7` and `python3.8` interpreters. Core committers, use this section to: -* Guide your instinct and decisions as a core committer -* Limit the codebase from growing infinitely +- Guide your instinct and decisions as a core committer +- Limit the codebase from growing infinitely #### Command-Line Accessible -* Provides a command-line utility that creates projects from cookiecutters -* Extremely easy to use without having to think too hard -* Flexible for more complex use via optional arguments +- Provides a command-line utility that creates projects from cookiecutters +- Extremely easy to use without having to think too hard +- Flexible for more complex use via optional arguments #### API Accessible -* Entirely function-based and stateless (Class-free by intentional design) -* Usable in pieces for developers of template generation tools +- Entirely function-based and stateless (Class-free by intentional design) +- Usable in pieces for developers of template generation tools #### Being Jinja2-specific -* Sets a standard baseline for project template creators, facilitating reuse -* Minimizes the learning curve for those who already use Flask or Django -* Minimizes scope of Cookiecutter codebase +- Sets a standard baseline for project template creators, facilitating reuse +- Minimizes the learning curve for those who already use Flask or Django +- Minimizes scope of Cookiecutter codebase #### Extensible Being extendable by people with different ideas for Jinja2-based project template tools. -* Entirely function-based -* Aim for statelessness -* Lets anyone write more opinionated tools +- Entirely function-based +- Aim for statelessness +- Lets anyone write more opinionated tools Freedom for Cookiecutter users to build and extend. -* No officially-maintained cookiecutter templates, only ones by individuals -* Commercial project-friendly licensing, allowing for private cookiecutters and private Cookiecutter-based tools +- No officially-maintained cookiecutter templates, only ones by individuals +- Commercial project-friendly licensing, allowing for private cookiecutters and private Cookiecutter-based tools #### Fast and Focused Cookiecutter is designed to do one thing, and do that one thing very well. -* Cover the use cases that the core committers need, and as little as possible beyond that :) -* Generates project templates from the command-line or API, nothing more -* Minimize internal line of code (LOC) count -* Ultra-fast project generation for high performance downstream tools +- Cover the use cases that the core committers need, and as little as possible beyond that :) +- Generates project templates from the command-line or API, nothing more +- Minimize internal line of code (LOC) count +- Ultra-fast project generation for high performance downstream tools #### Inclusive -* Cross-platform and cross-version support are more important than features/functionality -* Fixing Windows bugs even if it's a pain, to allow for use by more beginner coders +- Cross-platform and cross-version support are more important than features/functionality +- Fixing Windows bugs even if it's a pain, to allow for use by more beginner coders #### Stable -* Aim for 100% test coverage and covering corner cases -* No pull requests will be accepted that drop test coverage on any platform, including Windows -* Conservative decisions patterned after CPython's conservative decisions with stability in mind -* Stable APIs that tool builders can rely on -* New features require a +1 from 3 core committers +- Aim for 100% test coverage and covering corner cases +- No pull requests will be accepted that drop test coverage on any platform, including Windows +- Conservative decisions patterned after CPython's conservative decisions with stability in mind +- Stable APIs that tool builders can rely on +- New features require a +1 from 3 core committers #### VCS-Hosted Templates Cookiecutter project templates are intentionally hosted VCS repos as-is. -* They are easily forkable -* It's easy for users to browse forks and files -* They are searchable via standard Github/Bitbucket/other search interface -* Minimizes the need for packaging-related cruft files -* Easy to create a public project template and host it for free -* Easy to collaborate +- They are easily forkable +- It's easy for users to browse forks and files +- They are searchable via standard Github/Bitbucket/other search interface +- Minimizes the need for packaging-related cruft files +- Easy to create a public project template and host it for free +- Easy to collaborate ### Process: Pull Requests If a pull request is untriaged: -* Look at the roadmap -* Set it for the milestone where it makes the most sense -* Add it to the roadmap +- Look at the roadmap +- Set it for the milestone where it makes the most sense +- Add it to the roadmap How to prioritize pull requests, from most to least important: -* Fixes for broken tests. Broken means broken on any supported platform or Python version. -* Extra tests to cover corner cases. -* Minor edits to docs. -* Bug fixes. -* Major edits to docs. -* Features. +- Fixes for broken tests. Broken means broken on any supported platform or Python version. +- Extra tests to cover corner cases. +- Minor edits to docs. +- Bug fixes. +- Major edits to docs. +- Features. #### Pull Requests Review Guidelines -- Think carefully about the long-term implications of the change. How will it affect existing projects that are dependent on this? If this is complicated, do we really want to maintain it forever? -- Take the time to get things right, PRs almost always require additional improvements to meet the bar for quality. **Be very strict about quality.** -- When you merge a pull request take care of closing/updating every related issue explaining how they were affected by those changes. Also, remember to add the author to `AUTHORS.md`. +- Think carefully about the long-term implications of the change. + How will it affect existing projects that are dependent on this? + If this is complicated, do we really want to maintain it forever? +- Take the time to get things right, PRs almost always require additional improvements to meet the bar for quality. + **Be very strict about quality.** +- When you merge a pull request take care of closing/updating every related issue explaining how they were affected by those changes. + Also, remember to add the author to `AUTHORS.md`. ### Process: Issues @@ -307,12 +322,12 @@ Due dates are flexible. Core committers can change them as needed. Note that Git How to number milestones: -* Follow semantic versioning. Look at: [http://semver.org](http://semver.org) +- Follow semantic versioning. Look at: [http://semver.org](http://semver.org) Milestone size: -* If a milestone contains too much, move some to the next milestone. -* Err on the side of more frequent patch releases. +- If a milestone contains too much, move some to the next milestone. +- Err on the side of more frequent patch releases. ### Process: Your own code changes @@ -321,23 +336,29 @@ This rule applies to all the core committers. Exceptions: -* Minor corrections and fixes to pull requests submitted by others. -* While making a formal release, the release manager can make necessary, appropriate changes. -* Small documentation changes that reinforce existing subject matter. Most commonly being, but not limited to spelling and grammar corrections. +- Minor corrections and fixes to pull requests submitted by others. +- While making a formal release, the release manager can make necessary, appropriate changes. +- Small documentation changes that reinforce existing subject matter. + Most commonly being, but not limited to spelling and grammar corrections. ### Responsibilities -* Ensure cross-platform compatibility for every change that's accepted. Windows, macOS and Linux. -* Create issues for any major changes and enhancements that you wish to make. Discuss things transparently and get community feedback. -* Don't add any classes to the codebase unless absolutely needed. Err on the side of using functions. -* Keep feature versions as small as possible, preferably one new feature per version. -* Be welcoming to newcomers and encourage diverse new contributors from all backgrounds. Look at [Code of Conduct](CODE_OF_CONDUCT.md). +- Ensure cross-platform compatibility for every change that's accepted. Windows, macOS and Linux. +- Create issues for any major changes and enhancements that you wish to make. + Discuss things transparently and get community feedback. +- Don't add any classes to the codebase unless absolutely needed. + Err on the side of using functions. +- Keep feature versions as small as possible, preferably one new feature per version. +- Be welcoming to newcomers and encourage diverse new contributors from all backgrounds. + Look at [Code of Conduct](CODE_OF_CONDUCT.md). ### Becoming a Core Committer Contributors may be given core commit privileges. Preference will be given to those with: -1. Past contributions to Cookiecutter and other open-source projects. Contributions to Cookiecutter include both code (both accepted and pending) and friendly participation in the issue tracker. Quantity and quality are considered. +1. Past contributions to Cookiecutter and other open-source projects. + Contributions to Cookiecutter include both code (both accepted and pending) and friendly participation in the issue tracker. + Quantity and quality are considered. 2. A coding style that the other core committers find simple, minimal, and clean. 3. Access to resources for cross-platform development and testing. 4. Time to devote to the project regularly. diff --git a/HISTORY.md b/HISTORY.md index 5fc9fd5a9..b39699c1b 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -4,10 +4,15 @@ History is important, but our current roadmap can be found [here](https://github ## 2.0.2 (2021-12-27) +*Remark: This release never made it to official PyPI* + * Fix Python version number in cookiecutter --version and test on Python 3.10 (#1621) @ozer550 * Removed changes related to setuptools_scm (#1629) @audreyfeldroy @ozer550 ## 2.0.1 (2021-12-11) + +*Remark: This release never made it to official PyPI* + ### Breaking Changes * Release preparation for 2.0.1rc1 (#1608) @audreyfeldroy @@ -105,7 +110,7 @@ History is important, but our current roadmap can be found [here](https://github ## 1.7.1 (2020-04-21) This release was focused on internal code and CI/CD changes. During this release -all code was verified to match pep8, pep257 and other code-styling guides. +all code was verified to match pep8, pep257 and other code-styling guides. Project CI/CD was significantly changed, Windows platform checks based on Appveyor engine was replaced by GitHub actions tests. Appveyor was removed. Also our CI/CD was extended with Mac builds, to verify project builds on Apple devices. @@ -773,7 +778,7 @@ Other changes: $ cookiecutter cookiecutter-pypackage/ # Create project from the cookiecutter-pypackage.git repo template $ cookiecutter https://github.com/audreyr/cookiecutter-pypackage.git -``` +``` * Can now use Cookiecutter from Python as a package: diff --git a/Makefile b/Makefile index 71ea835bd..2dc6aa3aa 100644 --- a/Makefile +++ b/Makefile @@ -63,6 +63,10 @@ docs: ## Generate Sphinx HTML documentation, including API docs @rm -f docs/cookiecutter.rst @sphinx-apidoc -o docs/ cookiecutter @rm -f docs/modules.rst + @sed -i 's/cookiecutter package/===\nAPI\n===/' docs/cookiecutter.rst + @sed -i 's/====================//' docs/cookiecutter.rst + @sed -i 's/Submodules/This is the Cookiecutter modules API documentation./' docs/cookiecutter.rst + @sed -i 's/^----------$$//' docs/cookiecutter.rst @$(MAKE) -C docs clean @$(MAKE) -C docs html @$(BROWSER) docs/_build/html/index.html diff --git a/README.md b/README.md index a954feca2..38de8e205 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,7 @@ [![docs](https://readthedocs.org/projects/cookiecutter/badge/?version=latest)](https://readthedocs.org/projects/cookiecutter/?badge=latest) [![Code Quality](https://img.shields.io/scrutinizer/g/cookiecutter/cookiecutter.svg)](https://scrutinizer-ci.com/g/cookiecutter/cookiecutter/?branch=master) -A command-line utility that creates projects from **cookiecutters** (project -templates), e.g. creating a Python package project from a Python package project -template. +A command-line utility that creates projects from **cookiecutters** (project templates), e.g. creating a Python package project from a Python package project template. - Documentation: [https://cookiecutter.readthedocs.io](https://cookiecutter.readthedocs.io) - GitHub: [https://github.com/cookiecutter/cookiecutter](https://github.com/cookiecutter/cookiecutter) @@ -23,64 +21,44 @@ template. - Cross-platform: Windows, Mac, and Linux are officially supported. - You don't have to know/write Python code to use Cookiecutter. -- Works with Python 3.7, 3.8, 3.9. +- Works with Python 3.7, 3.8, 3.9., 3.10 - Project templates can be in any programming language or markup format: Python, JavaScript, Ruby, CoffeeScript, RST, Markdown, CSS, HTML, you name it. You can use multiple languages in the same project template. + +### For users of existing templates + - Simple command line usage: -```bash -# Create project from the cookiecutter-pypackage.git repo template -# You'll be prompted to enter values. -# Then it'll create your Python package in the current working directory, -# based on those values. -$ cookiecutter https://github.com/audreyfeldroy/cookiecutter-pypackage -# For the sake of brevity, repos on GitHub can just use the 'gh' prefix -$ cookiecutter gh:audreyfeldroy/cookiecutter-pypackage -``` + ```bash + # Create project from the cookiecutter-pypackage.git repo template + # You'll be prompted to enter values. + # Then it'll create your Python package in the current working directory, + # based on those values. + $ cookiecutter https://github.com/audreyfeldroy/cookiecutter-pypackage + # For the sake of brevity, repos on GitHub can just use the 'gh' prefix + $ cookiecutter gh:audreyfeldroy/cookiecutter-pypackage + ``` - Use it at the command line with a local template: -```bash -# Create project in the current working directory, from the local -# cookiecutter-pypackage/ template -$ cookiecutter cookiecutter-pypackage/ -``` + ```bash + # Create project in the current working directory, from the local + # cookiecutter-pypackage/ template + $ cookiecutter cookiecutter-pypackage/ + ``` - Or use it from Python: -```py -from cookiecutter.main import cookiecutter - -# Create project from the cookiecutter-pypackage/ template -cookiecutter('cookiecutter-pypackage/') - -# Create project from the cookiecutter-pypackage.git repo template -cookiecutter('https://github.com/audreyfeldroy/cookiecutter-pypackage.git') -``` - -- Directory names and filenames can be templated. For example: + ```py + from cookiecutter.main import cookiecutter -```py -{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}.py -``` + # Create project from the cookiecutter-pypackage/ template + cookiecutter('cookiecutter-pypackage/') -- Supports unlimited levels of directory nesting. -- 100% of templating is done with Jinja2. This includes file and directory names. -- Simply define your template variables in a `cookiecutter.json` file. For example: - -```json -{ - "full_name": "Audrey Roy Greenfeld", - "email": "audreyr@gmail.com", - "project_name": "Complexity", - "repo_name": "complexity", - "project_short_description": "Refreshingly simple static site generator.", - "release_date": "2013-07-10", - "year": "2013", - "version": "0.1.1" -} -``` + # Create project from the cookiecutter-pypackage.git repo template + cookiecutter('https://github.com/audreyfeldroy/cookiecutter-pypackage.git') + ``` - Unless you suppress it with `--no-input`, you are prompted for input: - Prompts are the keys in `cookiecutter.json`. @@ -88,78 +66,94 @@ cookiecutter('https://github.com/audreyfeldroy/cookiecutter-pypackage.git') - Prompts are shown in order. - Cross-platform support for `~/.cookiecutterrc` files: -```yaml -default_context: - full_name: "Audrey Roy Greenfeld" - email: "audreyr@gmail.com" - github_username: "audreyfeldroy" -cookiecutters_dir: "~/.cookiecutters/" -``` - -- Cookiecutters (cloned Cookiecutter project templates) are put into - `~/.cookiecutters/` by default, or cookiecutters_dir if specified. -- If you have already cloned a cookiecutter into `~/.cookiecutters/`, - you can reference it by directory name: - -```bash -# Clone cookiecutter-pypackage -$ cookiecutter gh:audreyfeldroy/cookiecutter-pypackage -# Now you can use the already cloned cookiecutter by name -$ cookiecutter cookiecutter-pypackage -``` - -- You can use local cookiecutters, or remote cookiecutters directly from Git - repos or from Mercurial repos on Bitbucket. -- Default context: specify key/value pairs that you want used as defaults - whenever you generate a project. + ```yaml + default_context: + full_name: "Audrey Roy Greenfeld" + email: "audreyr@gmail.com" + github_username: "audreyfeldroy" + cookiecutters_dir: "~/.cookiecutters/" + ``` + +- Cookiecutters (cloned Cookiecutter project templates) are put into `~/.cookiecutters/` by default, or cookiecutters_dir if specified. +- If you have already cloned a cookiecutter into `~/.cookiecutters/`, you can reference it by directory name: + + ```bash + # Clone cookiecutter-pypackage + $ cookiecutter gh:audreyfeldroy/cookiecutter-pypackage + # Now you can use the already cloned cookiecutter by name + $ cookiecutter cookiecutter-pypackage + ``` + +- You can use local cookiecutters, or remote cookiecutters directly from Git repos or from Mercurial repos on Bitbucket. +- Default context: specify key/value pairs that you want used as defaults whenever you generate a project. - Inject extra context with command-line arguments: -```bash -cookiecutter --no-input gh:msabramo/cookiecutter-supervisor program_name=foobar startsecs=10 -``` + ```bash + cookiecutter --no-input gh:msabramo/cookiecutter-supervisor program_name=foobar startsecs=10 + ``` - Direct access to the Cookiecutter API allows for injection of extra context. -- Pre- and post-generate hooks: Python or shell scripts to run before or after - generating a project. - Paths to local projects can be specified as absolute or relative. -- Projects generated to your current directory or to target directory if - specified with `-o` option. +- Projects generated to your current directory or to target directory if specified with `-o` option. + +### For template creators + +- Supports unlimited levels of directory nesting. +- 100% of templating is done with Jinja2. +- Both, directory names and filenames can be templated. + For example: + + ```py + {{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}.py + ``` +- Simply define your template variables in a `cookiecutter.json` file. + For example: + + ```json + { + "full_name": "Audrey Roy Greenfeld", + "email": "audreyr@gmail.com", + "project_name": "Complexity", + "repo_name": "complexity", + "project_short_description": "Refreshingly simple static site generator.", + "release_date": "2013-07-10", + "year": "2013", + "version": "0.1.1" + } + ``` +- Pre- and post-generate hooks: Python or shell scripts to run before or after generating a project. ## Available Cookiecutters -Making great cookies takes a lot of cookiecutters and contributors. We're so -pleased that there are many Cookiecutter project templates to choose from. We -hope you find a cookiecutter that is just right for your needs. +Making great cookies takes a lot of cookiecutters and contributors. +We're so pleased that there are many Cookiecutter project templates to choose from. +We hope you find a cookiecutter that is just right for your needs. -## A Pantry Full of Cookiecutters +### A Pantry Full of Cookiecutters -The best place to start searching for specific and ready to use cookiecutter -template is [Github search](https://github.com/search?q=cookiecutter&type=Repositories). +The best place to start searching for specific and ready to use cookiecutter template is [Github search](https://github.com/search?q=cookiecutter&type=Repositories). Just type `cookiecutter` and you will discover over 4000 related repositories. -We also recommend you to check related GitHub topics. For general search use -[cookiecutter-template](https://github.com/topics/cookiecutter-template). -For specific topics try to use `cookiecutter-yourtopic`, like -`cookiecutter-python` or `cookiecutter-datascience`. This is a new GitHub feature, -so not all active repositories use it at the moment. +We also recommend you to check related GitHub topics. +For general search use [cookiecutter-template](https://github.com/topics/cookiecutter-template). +For specific topics try to use `cookiecutter-yourtopic`, like `cookiecutter-python` or `cookiecutter-datascience`. +This is a new GitHub feature, so not all active repositories use it at the moment. -If you are template developer please add related -[topics](https://help.github.com/en/github/administering-a-repository/classifying-your-repository-with-topics) -with `cookiecutter` prefix to you repository. We believe it will make it more -discoverable. You are almost not limited in topics amount, use it! +If you are template developer please add related [topics](https://help.github.com/en/github/administering-a-repository/classifying-your-repository-with-topics) with `cookiecutter` prefix to you repository. +We believe it will make it more discoverable. +You are almost not limited in topics amount, use it! -## Cookiecutter Specials +### Cookiecutter Specials These Cookiecutters are maintained by the cookiecutter team: - [cookiecutter-pypackage](https://github.com/audreyfeldroy/cookiecutter-pypackage): - [@audreyfeldroy's](https://github.com/audreyfeldroy) ultimate Python package project template. + ultimate Python package project template by [@audreyfeldroy's](https://github.com/audreyfeldroy). - [cookiecutter-django](https://github.com/pydanny/cookiecutter-django): - A bleeding edge Django project template with Bootstrap 4, customizable users app, - starter templates, working user registration, celery setup, and much more. + a framework for jumpstarting production-ready Django projects quickly. + It is bleeding edge with Bootstrap 5, customizable users app, starter templates, working user registration, celery setup, and much more. - [cookiecutter-pytest-plugin](https://github.com/pytest-dev/cookiecutter-pytest-plugin): - Minimal Cookiecutter template for authoring [pytest](https://docs.pytest.org/) - plugins that help you to write better programs. + Minimal Cookiecutter template for authoring [pytest](https://docs.pytest.org/) plugins that help you to write better programs. ## Community @@ -170,27 +164,21 @@ Stuck? Try one of the following: - See the [Troubleshooting](https://cookiecutter.readthedocs.io/en/latest/troubleshooting.html) page. - Ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/cookiecutter). -- You are strongly encouraged to - [file an issue](https://github.com/cookiecutter/cookiecutter/issues?q=is%3Aopen) - about the problem, even if it's just "I can't get it to work on this cookiecutter" - with a link to your cookiecutter. Don't worry about naming/pinpointing the issue - properly. -- Ask for help on [Discord](https://discord.gg/9BrxzPKuEW) - if you must (but please try one of the other options first, so that others - can benefit from the discussion). +- You are strongly encouraged to [file an issue](https://github.com/cookiecutter/cookiecutter/issues?q=is%3Aopen) about the problem. + Do it even if it's just "I can't get it to work on this cookiecutter" with a link to your cookiecutter. + Don't worry about naming/pinpointing the issue properly. +- Ask for help on [Discord](https://discord.gg/9BrxzPKuEW) if you must (but please try one of the other options first, so that others can benefit from the discussion). Development on Cookiecutter is community-driven: -- Huge thanks to all the [contributors](AUTHORS.md) who have pitched in to help - make Cookiecutter an even better tool. -- Everyone is invited to contribute. Read the - [contributing instructions](CONTRIBUTING.md), then get started. -- Connect with other Cookiecutter contributors and users on - [Discord](https://discord.gg/9BrxzPKuEW) +- Huge thanks to all the [contributors](AUTHORS.md) who have pitched in to help make Cookiecutter an even better tool. +- Everyone is invited to contribute. + Read the [contributing instructions](CONTRIBUTING.md), then get started. +- Connect with other Cookiecutter contributors and users on [Discord](https://discord.gg/9BrxzPKuEW) (note: due to work and other commitments, a core committer might not always be available) -Encouragement is unbelievably motivating. If you want more work done on -Cookiecutter, show support: +Encouragement is unbelievably motivating. +If you want more work done on Cookiecutter, show support: - Thank a core committer for their efforts. - Star [Cookiecutter on GitHub](https://github.com/cookiecutter/cookiecutter). @@ -198,39 +186,35 @@ Cookiecutter, show support: Got criticism or complaints? -- [File an issue](https://github.com/cookiecutter/cookiecutter/issues?q=is%3Aopen) - so that Cookiecutter can be improved. Be friendly and constructive about what - could be better. Make detailed suggestions. -- **Keep us in the loop so that we can help.** For example, if you are - discussing problems with Cookiecutter on a mailing list, - [file an issue](https://github.com/cookiecutter/cookiecutter/issues?q=is%3Aopen) - where you link to the discussion thread and/or cc at least 1 core committer on the email. -- Be encouraging. A comment like "This function ought to be rewritten like this" - is much more likely to result in action than a comment like "Eww, look how bad - this function is." +- [File an issue](https://github.com/cookiecutter/cookiecutter/issues?q=is%3Aopen) so that Cookiecutter can be improved. + Be friendly and constructive about what could be better. + Make detailed suggestions. +- **Keep us in the loop so that we can help.** + For example, if you are discussing problems with Cookiecutter on a mailing list, [file an issue](https://github.com/cookiecutter/cookiecutter/issues?q=is%3Aopen) where you link to the discussion thread and/or cc at least 1 core committer on the email. +- Be encouraging. + A comment like "This function ought to be rewritten like this" is much more likely to result in action than a comment like "Eww, look how bad this function is." Waiting for a response to an issue/question? -- Be patient and persistent. All issues are on the core committer team's radar - and will be considered thoughtfully, but we have a lot of issues to work through. +- Be patient and persistent. All issues are on the core committer team's radar and will be considered thoughtfully, but we have a lot of issues to work through. If urgent, it's fine to ping a core committer in the issue with a reminder. - Ask others to comment, discuss, review, etc. - Search the Cookiecutter repo for issues related to yours. - Need a fix/feature/release/help urgently, and can't wait? - [@audreyfeldroy](https://github.com/audreyfeldroy) is available for hire for consultation - or custom development. + [@audreyfeldroy](https://github.com/audreyfeldroy) is available for hire for consultation or custom development. ## Support This Project -This project is run by volunteers. Shortly we will be providing means for -organizations and individuals to support the project. +This project is run by volunteers. +Shortly we will be providing means for organizations and individuals to support the project. ## Code of Conduct -Everyone interacting in the Cookiecutter project's codebases, issue trackers, -chat rooms, and mailing lists is expected to follow the -[PyPA Code of Conduct](https://www.pypa.io/en/latest/code-of-conduct/). +Everyone interacting in the Cookiecutter project's codebases and documentation is expected to follow the [PyPA Code of Conduct](https://www.pypa.io/en/latest/code-of-conduct/). +This includes, but is not limited to, issue trackers, chat rooms, mailing lists, and other virtual or in real life communication. ## Creator / Leader This project was created and is led by [Audrey Roy Greenfeld](https://github.com/audreyfeldroy). + +She is supported by a team of maintainers. diff --git a/docs/HelloCookieCutter1 b/docs/HelloCookieCutter1 deleted file mode 160000 index 239ea6928..000000000 --- a/docs/HelloCookieCutter1 +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 239ea692896301eaa280dd407fdd4d5c55cf6998 diff --git a/docs/advanced/calling_from_python.rst b/docs/advanced/calling_from_python.rst index 4c7f2e9ad..b497b6bf0 100644 --- a/docs/advanced/calling_from_python.rst +++ b/docs/advanced/calling_from_python.rst @@ -3,7 +3,9 @@ Calling Cookiecutter Functions From Python ------------------------------------------ -You can use Cookiecutter from Python:: +You can use Cookiecutter from Python: + +.. code-block:: python from cookiecutter.main import cookiecutter @@ -13,6 +15,6 @@ You can use Cookiecutter from Python:: # Create project from the cookiecutter-pypackage.git repo template cookiecutter('https://github.com/audreyr/cookiecutter-pypackage.git') -This is useful if, for example, you're writing a web framework and need to -provide developers with a tool similar to `django-admin.py startproject` or -`npm init`. +This is useful if, for example, you're writing a web framework and need to provide developers with a tool similar to `django-admin.py startproject` or `npm init`. + +See the :ref:`API Reference ` for more details. diff --git a/docs/advanced/choice_variables.rst b/docs/advanced/choice_variables.rst index ccb35d4bf..706d53947 100644 --- a/docs/advanced/choice_variables.rst +++ b/docs/advanced/choice_variables.rst @@ -1,17 +1,21 @@ .. _choice-variables: -Choice Variables (1.1+) ------------------------ +Choice Variables +---------------- -Choice variables provide different choices when creating a project. Depending on a user's choice -the template renders things differently. +*New in Cookiecutter 1.1* + +Choice variables provide different choices when creating a project. +Depending on a user's choice the template renders things differently. Basic Usage ~~~~~~~~~~~ Choice variables are regular key / value pairs, but with the value being a list of strings. -For example, if you provide the following choice variable in your ``cookiecutter.json``:: +For example, if you provide the following choice variable in your ``cookiecutter.json``: + +.. code-block:: JSON { "license": ["MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0"] @@ -28,8 +32,9 @@ you'd get the following choices when running Cookiecutter:: Depending on an user's choice, a different license is rendered by Cookiecutter. -The above ``license`` choice variable creates ``cookiecutter.license``, which -can be used like this:: +The above ``license`` choice variable creates ``cookiecutter.license``, which can be used like this: + +.. code-block:: html+jinja {%- if cookiecutter.license == "MIT" -%} # Possible license content here @@ -41,7 +46,10 @@ can be used like this:: Cookiecutter is using `Jinja2's if conditional expression `_ to determine the correct license. -The created choice variable is still a regular Cookiecutter variable and can be used like this:: +The created choice variable is still a regular Cookiecutter variable and can be used like this: + +.. code-block:: html+jinja + License ------- @@ -53,7 +61,9 @@ Overwriting Default Choice Values Choice Variables are overwritable using a :ref:`user-config` file. -For example, a choice variable can be created in ``cookiecutter.json`` by using a list as value:: +For example, a choice variable can be created in ``cookiecutter.json`` by using a list as value: + +.. code-block:: JSON { "license": ["MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0"] diff --git a/docs/advanced/copy_without_render.rst b/docs/advanced/copy_without_render.rst index 2cdb68084..5e4bc008d 100644 --- a/docs/advanced/copy_without_render.rst +++ b/docs/advanced/copy_without_render.rst @@ -5,7 +5,10 @@ Copy without Render *New in Cookiecutter 1.1* -To avoid rendering directories and files of a cookiecutter, the `_copy_without_render` key can be used in the `cookiecutter.json`. The value of this key accepts a list of Unix shell-style wildcards:: +To avoid rendering directories and files of a cookiecutter, the ``_copy_without_render`` key can be used in the ``cookiecutter.json``. +The value of this key accepts a list of Unix shell-style wildcards: + +.. code-block:: JSON { "project_slug": "sample", @@ -16,7 +19,12 @@ To avoid rendering directories and files of a cookiecutter, the `_copy_without_r ] } -**Note**: Only the content of the files will be copied without being rendered. The paths are subject to rendering. This allows you to write:: +**Note**: +Only the content of the files will be copied without being rendered. +The paths are subject to rendering. +This allows you to write: + +.. code-block:: JSON { "project_slug": "sample", @@ -25,4 +33,4 @@ To avoid rendering directories and files of a cookiecutter, the `_copy_without_r ] } -In this example, `{{cookiecutter.repo_name}}` will be rendered as expected but the html file content will be copied without rendering. +In this example, ``{{cookiecutter.repo_name}}`` will be rendered as expected but the html file content will be copied without rendering. diff --git a/docs/advanced/dict_variables.rst b/docs/advanced/dict_variables.rst index 1db841fa1..6142f4bd8 100644 --- a/docs/advanced/dict_variables.rst +++ b/docs/advanced/dict_variables.rst @@ -1,20 +1,21 @@ .. _dict-variables: -Dictionary Variables (1.5+) ---------------------------- +Dictionary Variables +-------------------- -Dictionary variables provide a way to define deep structured information when -rendering a template. +*New in Cookiecutter 1.5* + +Dictionary variables provide a way to define deep structured information when rendering a template. Basic Usage ~~~~~~~~~~~ -Dictionary variables are, as the name suggests, dictionaries of key-value -pairs. The dictionary values can, themselves, be other dictionaries and lists -- the data structure can be as deep as you need. +Dictionary variables are, as the name suggests, dictionaries of key-value pairs. +The dictionary values can, themselves, be other dictionaries and lists - the data structure can be as deep as you need. + +For example, you could provide the following dictionary variable in your ``cookiecutter.json``: -For example, you could provide the following dictionary variable in your -``cookiecutter.json``:: +.. code-block:: json { "project_slug": "new_project", @@ -38,8 +39,9 @@ For example, you could provide the following dictionary variable in your } -The above ``file_type`` dictionary variable creates -``cookiecutter.file_types``, which can be used like this:: +The above ``file_type`` dictionary variable creates ``cookiecutter.file_types``, which can be used like this: + +.. code-block:: html+jinja {% for extension, details in cookiecutter.file_types|dictsort %}
diff --git a/docs/advanced/directories.rst b/docs/advanced/directories.rst index cbec8e4ae..ba0596ded 100644 --- a/docs/advanced/directories.rst +++ b/docs/advanced/directories.rst @@ -1,14 +1,13 @@ .. _directories: -Organizing cookiecutters in directories (1.7+) ---------------------------------------------------- +Organizing cookiecutters in directories +--------------------------------------- *New in Cookiecutter 1.7* -Cookiecutter introduces the ability to organize several templates in one -repository or zip file, separating them by directories. This allows using -symlinks for general files. Here's an example repository demonstrating -this feature:: +Cookiecutter introduces the ability to organize several templates in one repository or zip file, separating them by directories. +This allows using symlinks for general files. +Here's an example repository demonstrating this feature:: https://github.com/user/repo-name.git ├── directory1-name/ @@ -18,6 +17,8 @@ this feature:: ├── {{cookiecutter.project_slug}}/ └── cookiecutter.json -To activate one of templates within a subdirectory, use the ``--directory`` option:: +To activate one of templates within a subdirectory, use the ``--directory`` option: + +.. code-block:: bash cookiecutter https://github.com/user/repo-name.git --directory="directory1-name" diff --git a/docs/advanced/hooks.rst b/docs/advanced/hooks.rst index c659fd407..d08cf9e75 100644 --- a/docs/advanced/hooks.rst +++ b/docs/advanced/hooks.rst @@ -1,12 +1,13 @@ .. _user-hooks: -Using Pre/Post-Generate Hooks (0.7.0+) -====================================== +Using Pre/Post-Generate Hooks +============================= -You can have Python or Shell scripts that run before and/or after your project -is generated. +*New in cookiecutter 0.7* -Put them in `hooks/` like this:: +You can have Python or Shell scripts that run before and/or after your project is generated. + +Put them in ``hooks/`` like this:: cookiecutter-something/ ├── {{cookiecutter.project_slug}}/ @@ -24,13 +25,11 @@ Shell scripts work similarly:: │ └── post_gen_project.sh └── cookiecutter.json -It shouldn't be too hard to extend Cookiecutter to work with other types of -scripts too. Pull requests are welcome. +It shouldn't be too hard to extend Cookiecutter to work with other types of scripts too. +Pull requests are welcome. -For portability, you should use Python scripts (with extension `.py`) for your -hooks, as these can be run on any platform. However, if you intend for your -template to only be run on a single platform, a shell script (or `.bat` file -on Windows) can be a quicker alternative. +For portability, you should use Python scripts (with extension `.py`) for your hooks, as these can be run on any platform. +However, if you intend for your template to only be run on a single platform, a shell script (or `.bat` file on Windows) can be a quicker alternative. Writing hooks ------------- @@ -40,25 +39,21 @@ Here are some details on how to write pre/post-generate hook scripts. Exit with an appropriate status ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Make sure your hook scripts work in a robust manner. If a hook script fails -(that is, `if it finishes with a nonzero exit status -`_), the project -generation will stop and the generated directory will be cleaned up. +Make sure your hook scripts work in a robust manner. +If a hook script fails (that is, `if it finishes with a nonzero exit status `_), the project generation will stop and the generated directory will be cleaned up. Current working directory ^^^^^^^^^^^^^^^^^^^^^^^^^ -When the hook scripts script are run, their current working directory is the -root of the generated project. This makes it easy for a post-generate hook to -find generated files using relative paths. +When the hook scripts script are run, their current working directory is the root of the generated project. +This makes it easy for a post-generate hook to find generated files using relative paths. Template variables are rendered in the script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Just like your project template, Cookiecutter also renders Jinja template -syntax in your scripts. This lets you incorporate Jinja template variables in -your scripts. For example, this line of Python sets ``module_name`` to the -value of the ``cookiecutter.module_name`` template variable: +Just like your project template, Cookiecutter also renders Jinja template syntax in your scripts. +This lets you incorporate Jinja template variables in your scripts. +For example, this line of Python sets ``module_name`` to the value of the ``cookiecutter.module_name`` template variable: .. code-block:: python @@ -67,9 +62,7 @@ value of the ``cookiecutter.module_name`` template variable: Example: Validating template variables -------------------------------------- -Here is an example of a pre-generate hook script, defined at -``hooks/pre_gen_project.py``, that validates a template variable before generating the -project: +Here is an example of a pre-generate hook script, defined at ``hooks/pre_gen_project.py``, that validates a template variable before generating the project: .. code-block:: python @@ -90,12 +83,10 @@ project: Example: Conditional files / directories ---------------------------------------- -Here is an example of a post-generate hook script, defined at -``hooks/post_gen_project.py``, on how to achieve conditional control of files and -directories after generating the project. +Here is an example of a post-generate hook script. +The file ``hooks/post_gen_project.py`` shows how to achieve conditional control of files and directories after generating the project. -The script ensures that the directory structure is as expected by -removing unwanted files and directories: +The script ensures that the directory structure is as expected by removing unwanted files and directories: .. code-block:: python diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst index 66d5faadd..d2111ad4b 100644 --- a/docs/advanced/index.rst +++ b/docs/advanced/index.rst @@ -17,7 +17,6 @@ Various advanced topics regarding cookiecutter usage. private_variables copy_without_render replay - cli_options choice_variables dict_variables template_extensions diff --git a/docs/advanced/injecting_context.rst b/docs/advanced/injecting_context.rst index 32927c07f..5561b3d83 100644 --- a/docs/advanced/injecting_context.rst +++ b/docs/advanced/injecting_context.rst @@ -3,17 +3,30 @@ Injecting Extra Context ----------------------- -You can specify an `extra_context` dictionary that will override values from `cookiecutter.json` or `.cookiecutterrc`:: +You can specify an ``extra_context`` dictionary that will override values from ``cookiecutter.json`` or ``.cookiecutterrc``: - cookiecutter('cookiecutter-pypackage/', - extra_context={'project_name': 'TheGreatest'}) +.. code-block:: python + + cookiecutter( + 'cookiecutter-pypackage/', + extra_context={'project_name': 'TheGreatest'}, + ) + +This works as command-line parameters as well: + +.. code-block:: bash + + cookiecutter --no-input cookiecutter-pypackage/ project_name=TheGreatest + +You will also need to add these keys to the ``cookiecutter.json`` or ``.cookiecutterrc``. -You will also need to add these keys to the `cookiecutter.json` or `.cookiecutterrc`. Example: Injecting a Timestamp ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you have ``cookiecutter.json`` that has the following keys:: +If you have ``cookiecutter.json`` that has the following keys: + +.. code-block:: JSON { "timestamp": "{{ cookiecutter.timestamp }}" @@ -21,7 +34,9 @@ If you have ``cookiecutter.json`` that has the following keys:: This Python script will dynamically inject a timestamp value as the project is -generated:: +generated: + +.. code-block:: python from cookiecutter.main import cookiecutter @@ -34,6 +49,6 @@ generated:: How this works: -1. The script uses `datetime` to get the current UTC time in ISO format. -2. To generate the project, `cookiecutter()` is called, passing the timestamp - in as context via the `extra_context` dict. +1. The script uses ``datetime`` to get the current UTC time in ISO format. +2. To generate the project, ``cookiecutter()`` is called, passing the timestamp + in as context via the ``extra_context``` dict. diff --git a/docs/advanced/local_extensions.rst b/docs/advanced/local_extensions.rst index bf87caf7b..9a3d4b940 100644 --- a/docs/advanced/local_extensions.rst +++ b/docs/advanced/local_extensions.rst @@ -1,4 +1,4 @@ -.. _`template extensions`: +.. _`local extensions`: Local Extensions ---------------- @@ -35,8 +35,8 @@ It will contain a ``main.py`` file, containing the following (for instance): This will register the ``foobar`` filter for the template. -For many cases, this will be unneccessarily complicated. It's likely that we'd only want to register a single function -as a filter. For this, we can use the ``simple_filter`` decorator: +For many cases, this will be unneccessarily complicated. +It's likely that we'd only want to register a single function as a filter. For this, we can use the ``simple_filter`` decorator: .. code-block:: json diff --git a/docs/advanced/new_line_characters.rst b/docs/advanced/new_line_characters.rst index 64f009898..e75ca9fcc 100644 --- a/docs/advanced/new_line_characters.rst +++ b/docs/advanced/new_line_characters.rst @@ -5,19 +5,22 @@ Working with line-ends special symbols LF/CRLF *New in Cookiecutter 2.0* -Before version 2.0 Cookiecutter silently used system line end character. -LF for POSIX and CRLF for Windows. Since version 2.0 this behaviour changed -and now can be forced at template level. +.. note:: -By default Cookiecutter now check every file at render stage and use same line -end as in source. This allow template developers to have both types of files in -the same template. Developers should correctly configure their `.gitattributes` -file to avoid line-end character overwrite by git. + Before version 2.0 Cookiecutter silently used system line end character. + LF for POSIX and CRLF for Windows. + Since version 2.0 this behaviour changed and now can be forced at template level. -Special template variable `_new_lines` was added in Cookiecutter 2.0. -Acceptable variables: `'\n\r'` for CRLF and `'\n'` for POSIX. +By default Cookiecutter checks every file at render stage and uses the same line end as in source. +This allow template developers to have both types of files in the same template. +Developers should correctly configure their ``.gitattributes`` file to avoid line-end character overwrite by git. -Here is example how to force line endings to CRLF on any deployment:: +The special template variable ``_new_lines`` enforces a specific line ending. +Acceptable variables: ``'\n\r'`` for CRLF and ``'\n'`` for POSIX. + +Here is example how to force line endings to CRLF on any deployment: + +.. code-block:: JSON { "project_slug": "sample", diff --git a/docs/advanced/private_variables.rst b/docs/advanced/private_variables.rst index 08ba9d943..6d17268b3 100644 --- a/docs/advanced/private_variables.rst +++ b/docs/advanced/private_variables.rst @@ -3,7 +3,12 @@ Private Variables ----------------- -Cookiecutter allows the definition private variables - those the user will not be required to fill in - by prepending an underscore to the variable name. These can either be not rendered, by using a prepending underscore, or rendered, prepending a double underscore. For example, the ``cookiecutter.json``:: +Cookiecutter allows the definition private variables by prepending an underscore to the variable name. +The user will not be required to fill those variables in. +These can either be not rendered, by using a prepending underscore, or rendered, prepending a double underscore. +For example, the ``cookiecutter.json``: + +.. code-block:: JSON { "project_name": "Really cool project", @@ -11,7 +16,9 @@ Cookiecutter allows the definition private variables - those the user will not b "__rendered": "{{ cookiecutter.project_name|lower }}" } -Will be rendered as:: +Will be rendered as: + +.. code-block:: JSON { "project_name": "Really cool project", @@ -21,7 +28,11 @@ Will be rendered as:: The user will only be asked for ``project_name``. -Non-rendered private variables can be used for defining constants. An example of where you may wish to use private **rendered** variables is creating a Python package repository and want to enforce naming consistency. To ensure the repository and package name are based on the project name, you could create a ``cookiecutter.json`` such as:: +Non-rendered private variables can be used for defining constants. +An example of where you may wish to use private **rendered** variables is creating a Python package repository and want to enforce naming consistency. +To ensure the repository and package name are based on the project name, you could create a ``cookiecutter.json`` such as: + +.. code-block:: JSON { "project_name": "Project Name", diff --git a/docs/advanced/replay.rst b/docs/advanced/replay.rst index 14afbfd24..426f0274e 100644 --- a/docs/advanced/replay.rst +++ b/docs/advanced/replay.rst @@ -9,7 +9,9 @@ On invocation **Cookiecutter** dumps a json file to ``~/.cookiecutter_replay/`` In other words, it persists your **input** for a template and fetches it when you run the same template again. -Example for a replay file (which was created via ``cookiecutter gh:hackebrot/cookiedozer``):: +Example for a replay file (which was created via ``cookiecutter gh:hackebrot/cookiedozer``): + +.. code-block:: JSON { "cookiecutter": { @@ -28,27 +30,31 @@ Example for a replay file (which was created via ``cookiecutter gh:hackebrot/coo To fetch this context data without being prompted on the command line you can use either of the following methods. -Pass the according option on the CLI:: +Pass the according option on the CLI: + +.. code-block:: bash cookiecutter --replay gh:hackebrot/cookiedozer Or use the Python API:: +.. code-block:: python + from cookiecutter.main import cookiecutter cookiecutter('gh:hackebrot/cookiedozer', replay=True) - -This feature is comes in handy if, for instance, you want to create a new project from an updated template. +This feature comes in handy if, for instance, you want to create a new project from an updated template. Custom replay file ~~~~~~~~~~~~~~~~~~ *New in Cookiecutter 2.0* -To specify a custom filename, you can use the ``--replay-file`` option:: +To specify a custom filename, you can use the ``--replay-file`` option: + +.. code-block:: bash cookiecutter --replay-file ./cookiedozer.json gh:hackebrot/cookiedozer -This may be useful to run the same replay file over several machines, in tests -or when a user of the template reports a problem +This may be useful to run the same replay file over several machines, in tests or when a user of the template reports a problem. diff --git a/docs/advanced/suppressing_prompts.rst b/docs/advanced/suppressing_prompts.rst index 1f73ff9fd..1064ad965 100644 --- a/docs/advanced/suppressing_prompts.rst +++ b/docs/advanced/suppressing_prompts.rst @@ -3,12 +3,14 @@ Suppressing Command-Line Prompts -------------------------------- -To suppress the prompts asking for input, use `no_input`. +To suppress the prompts asking for input, use ``no_input``. Basic Example: Using the Defaults ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Cookiecutter will pick a default value if used with `no_input`:: +Cookiecutter will pick a default value if used with ``no_input``: + +.. code-block:: python from cookiecutter.main import cookiecutter cookiecutter( @@ -16,18 +18,21 @@ Cookiecutter will pick a default value if used with `no_input`:: no_input=True, ) -In this case it will be using the default defined in `cookiecutter.json` or `.cookiecutterrc`. +In this case it will be using the default defined in ``cookiecutter.json`` or ``.cookiecutterrc``. .. note:: - values from `cookiecutter.json` will be overridden by values from `.cookiecutterrc` + values from ``cookiecutter.json`` will be overridden by values from ``.cookiecutterrc`` Advanced Example: Defaults + Extra Context ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you combine an `extra_context` dict with the `no_input` argument, you can programmatically create the project with a set list of context parameters and without any command line prompts:: +If you combine an ``extra_context`` dict with the ``no_input`` argument, you can programmatically create the project with a set list of context parameters and without any command line prompts: + +.. code-block:: JSON cookiecutter('cookiecutter-pypackage/', no_input=True, extra_context={'project_name': 'TheGreatest'}) -See the :ref:`API Reference ` for more details. + +See also :ref:`injecting-extra-content` and the :ref:`API Reference ` for more details. diff --git a/docs/advanced/template_extensions.rst b/docs/advanced/template_extensions.rst index 940b87b2f..397460fa8 100644 --- a/docs/advanced/template_extensions.rst +++ b/docs/advanced/template_extensions.rst @@ -5,8 +5,8 @@ Template Extensions *New in Cookiecutter 1.4* -A template may extend the Cookiecutter environment with custom `Jinja2 extensions`_, -that can add extra filters, tests, globals or even extend the parser. +A template may extend the Cookiecutter environment with custom `Jinja2 extensions`_. +It can add extra filters, tests, globals or even extend the parser. To do so, a template author must specify the required extensions in ``cookiecutter.json`` as follows: @@ -20,12 +20,10 @@ To do so, a template author must specify the required extensions in ``cookiecutt On invocation Cookiecutter tries to import the extensions and add them to its environment respectively. -In the above example, Cookiecutter provides the additional tag `now`_, after -installing the `jinja2_time.TimeExtension`_ and enabling it in ``cookiecutter.json``. +In the above example, Cookiecutter provides the additional tag `now`_, after installing the `jinja2_time.TimeExtension`_ and enabling it in ``cookiecutter.json``. Please note that Cookiecutter will **not** install any dependencies on its own! -As a user you need to make sure you have all the extensions installed, before -running Cookiecutter on a template that requires custom Jinja2 extensions. +As a user you need to make sure you have all the extensions installed, before running Cookiecutter on a template that requires custom Jinja2 extensions. By default Cookiecutter includes the following extensions: @@ -38,8 +36,7 @@ By default Cookiecutter includes the following extensions: Jsonify extension ~~~~~~~~~~~~~~~~~ -The ``cookiecutter.extensions.JsonifyExtension`` extension provides a ``jsonify`` filter in templates -that converts a Python object to JSON: +The ``cookiecutter.extensions.JsonifyExtension`` extension provides a ``jsonify`` filter in templates that converts a Python object to JSON: .. code-block:: jinja @@ -56,10 +53,10 @@ Random string extension *New in Cookiecutter 1.7* -The ``cookiecutter.extensions.RandomStringExtension`` extension provides a ``random_ascii_string`` -method in templates that generates a random fixed-length string, optionally with punctuation. +The ``cookiecutter.extensions.RandomStringExtension`` extension provides a ``random_ascii_string`` method in templates that generates a random fixed-length string, optionally with punctuation. -Generate a random n-size character string. Example for n=12: +Generate a random n-size character string. +Example for n=12: .. code-block:: jinja @@ -71,8 +68,7 @@ Outputs: bIIUczoNvswh -The second argument controls if punctuation and special characters -``!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~`` should be present in the result: +The second argument controls if punctuation and special characters ``!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~`` should be present in the result: .. code-block:: jinja @@ -87,8 +83,7 @@ Outputs: Slugify extension ~~~~~~~~~~~~~~~~~ -The ``cookiecutter.extensions.SlugifyExtension`` extension provides a ``slugify`` filter in templates -that converts string into its underscored ("slugified") version: +The ``cookiecutter.extensions.SlugifyExtension`` extension provides a ``slugify`` filter in templates that converts string into its dashed ("slugified") version: .. code-block:: jinja @@ -96,20 +91,18 @@ that converts string into its underscored ("slugified") version: Would output: -.. code-block:: json +:: it-s-a-random-version -It is diferent from a mere replace of spaces since it also trates some special characters -such as `'` in the example above. The function accepts all arguments that can be passed to -the `slugify` function of python-slugify. For example to change the output from -`it-s-a-random-version` to `it_s_a_random_version`, the parameter `separator='_'` would -be passed to `slugify()`. +It is different from a mere replace of spaces since it also trates some special characters such as ``'`` in the example above. +The function accepts all arguments that can be passed to the ``slugify`` function of `python-slugify`_. +For example to change the output from ``it-s-a-random-version``` to ``it_s_a_random_version``, the ``separator`` parameter would be passed: ``slugify(separator='_')``. .. _`Jinja2 extensions`: http://jinja.pocoo.org/docs/latest/extensions/ .. _`now`: https://github.com/hackebrot/jinja2-time#now-tag .. _`jinja2_time.TimeExtension`: https://github.com/hackebrot/jinja2-time -.. _`python-slugify`: https://github.com/un33k/python-slugify +.. _`python-slugify`: https://pypi.org/project/python-slugify UUID4 extension ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/advanced/templates_in_context.rst b/docs/advanced/templates_in_context.rst index faccb3c72..f324c60fe 100644 --- a/docs/advanced/templates_in_context.rst +++ b/docs/advanced/templates_in_context.rst @@ -4,20 +4,21 @@ Templates in Context Values -------------------------------- The values (but not the keys!) of `cookiecutter.json` are also Jinja2 templates. -Values from user prompts are added to the context immediately, such that one -context value can be derived from previous values. This approach can potentially -save your user a lot of keystrokes by providing more sensible defaults. +Values from user prompts are added to the context immediately, such that one context value can be derived from previous values. +This approach can potentially save your user a lot of keystrokes by providing more sensible defaults. Basic Example: Templates in Context -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python packages show some patterns for their naming conventions: -* a human-readable project name -* a lowercase, dashed repository name -* an importable, dash-less package name +- a human-readable project name +- a lowercase, dashed repository name +- an importable, dash-less package name -Here is a `cookiecutter.json` with templated values for this pattern:: +Here is a `cookiecutter.json` with templated values for this pattern: + +.. code-block:: JSON { "project_name": "My New Project", @@ -25,13 +26,12 @@ Here is a `cookiecutter.json` with templated values for this pattern:: "pkg_name": "{{ cookiecutter.project_slug|replace('-', '') }}" } -If the user takes the defaults, or uses `no_input`, the templated values will -be: +If the user takes the defaults, or uses `no_input`, the templated values will be: -* `my-new-project` -* `mynewproject` +- `my-new-project` +- `mynewproject` Or, if the user gives `Yet Another New Project`, the values will be: -* `yet-another-new-project` -* `yetanothernewproject` +- ``yet-another-new-project`` +- ``yetanothernewproject`` diff --git a/docs/advanced/user_config.rst b/docs/advanced/user_config.rst index 96f500898..c7a8e9826 100644 --- a/docs/advanced/user_config.rst +++ b/docs/advanced/user_config.rst @@ -1,23 +1,29 @@ .. _user-config: -User Config (0.7.0+) -==================== +User Config +=========== -If you use Cookiecutter a lot, you'll find it useful to have a user config -file. By default Cookiecutter tries to retrieve settings from a `.cookiecutterrc` -file in your home directory. +*New in Cookiecutter 0.7* -From version 1.3.0 you can also specify a config file on the command line via ``--config-file``:: +If you use Cookiecutter a lot, you'll find it useful to have a user config file. +By default Cookiecutter tries to retrieve settings from a `.cookiecutterrc` file in your home directory. - $ cookiecutter --config-file /home/audreyr/my-custom-config.yaml cookiecutter-pypackage +*New in Cookiecutter 1.3* -Or you can set the ``COOKIECUTTER_CONFIG`` environment variable:: +You can also specify a config file on the command line via ``--config-file``. - $ export COOKIECUTTER_CONFIG=/home/audreyr/my-custom-config.yaml +.. code-block:: bash -If you wish to stick to the built-in config and not load any user config file at all, -use the cli option ``--default-config`` instead. Preventing Cookiecutter from loading -user settings is crucial for writing integration tests in an isolated environment. + cookiecutter --config-file /home/audreyr/my-custom-config.yaml cookiecutter-pypackage + +Or you can set the ``COOKIECUTTER_CONFIG`` environment variable: + +.. code-block:: bash + + export COOKIECUTTER_CONFIG=/home/audreyr/my-custom-config.yaml + +If you wish to stick to the built-in config and not load any user config file at all, use the CLI option ``--default-config`` instead. +Preventing Cookiecutter from loading user settings is crucial for writing integration tests in an isolated environment. Example user config: @@ -36,18 +42,19 @@ Example user config: Possible settings are: -* default_context: A list of key/value pairs that you want injected as context - whenever you generate a project with Cookiecutter. These values are treated - like the defaults in `cookiecutter.json`, upon generation of any project. -* cookiecutters_dir: Directory where your cookiecutters are cloned to when you - use Cookiecutter with a repo argument. -* replay_dir: Directory where Cookiecutter dumps context data to, which - you can fetch later on when using the :ref:`replay feature `. -* abbreviations: A list of abbreviations for cookiecutters. Abbreviations can - be simple aliases for a repo name, or can be used as a prefix, in the form - `abbr:suffix`. Any suffix will be inserted into the expansion in place of - the text `{0}`, using standard Python string formatting. With the above - aliases, you could use the `cookiecutter-pypackage` template simply by saying - `cookiecutter pp`, or `cookiecutter gh:audreyr/cookiecutter-pypackage`. - The `gh` (github), `bb` (bitbucket), and `gl` (gitlab) abbreviations shown - above are actually built in, and can be used without defining them yourself. +``default_context``: + A list of key/value pairs that you want injected as context whenever you generate a project with Cookiecutter. + These values are treated like the defaults in ``cookiecutter.json``, upon generation of any project. +``cookiecutters_dir`` + Directory where your cookiecutters are cloned to when you use Cookiecutter with a repo argument. +``replay_dir`` + Directory where Cookiecutter dumps context data to, which you can fetch later on when using the + :ref:`replay feature `. +``abbreviations`` + A list of abbreviations for cookiecutters. + Abbreviations can be simple aliases for a repo name, or can be used as a prefix, in the form ``abbr:suffix``. + Any suffix will be inserted into the expansion in place of the text ``{0}``, using standard Python string formatting. + With the above aliases, you could use the ``cookiecutter-pypackage`` template simply by saying ``cookiecutter pp``, or ``cookiecutter gh:audreyr/cookiecutter-pypackage``. + The ``gh`` (GitHub), ``bb`` (Bitbucket), and ``gl`` (Gitlab) abbreviations shown above are actually **built in**, and can be used without defining them yourself. + +Read also: :ref:`injecting-extra-content` diff --git a/docs/advanced/cli_options.rst b/docs/cli_options.rst similarity index 100% rename from docs/advanced/cli_options.rst rename to docs/cli_options.rst diff --git a/docs/conf.py b/docs/conf.py index 082a25d03..51648bd10 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -95,7 +95,7 @@ def __getattr__(cls, name): # General information about the project. project = 'cookiecutter' -copyright = '2013-2019, Audrey Roy and Cookiecutter community' +copyright = '2013-2022, Audrey Roy and Cookiecutter community' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -324,7 +324,7 @@ def __getattr__(cls, name): epub_title = 'cookiecutter' epub_author = 'Audrey Roy' epub_publisher = 'Audrey Roy and Cookiecutter community' -epub_copyright = '2013-2019, Audrey Roy and Cookiecutter community' +epub_copyright = '2013-2022, Audrey Roy and Cookiecutter community' # The language of the text. It defaults to the language option # or en if the language is not set. @@ -377,4 +377,4 @@ def __getattr__(cls, name): # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} +intersphinx_mapping = {'https://docs.python.org/3': None} diff --git a/docs/cookiecutter.rst b/docs/cookiecutter.rst index 790a21f7c..16c1c9dc1 100644 --- a/docs/cookiecutter.rst +++ b/docs/cookiecutter.rst @@ -1,8 +1,10 @@ +=== API === -Submodules ----------- + +This is the Cookiecutter modules API documentation. + cookiecutter.cli module ----------------------- @@ -132,7 +134,6 @@ cookiecutter.zipfile module :undoc-members: :show-inheritance: - Module contents --------------- diff --git a/docs/index.rst b/docs/index.rst index 15a953e63..14f5edbcf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ Cookiecutter: Better Project Templates ====================================== -Cookiecutter creates projects from project templates, e.g. Python package projects. +Cookiecutter creates projects from **cookiecutters** (project templates), e.g. Python package projects from Python package temnplates. Basics ------ @@ -18,9 +18,8 @@ Basics overview installation usage - tutorials - tutorial1 - tutorial2 + cli_options + tutorials/index advanced/index troubleshooting diff --git a/docs/installation.rst b/docs/installation.rst index d12709c37..068c6d9d9 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -12,13 +12,17 @@ Prerequisites Python interpreter ^^^^^^^^^^^^^^^^^^ -Install Python for your operating system. Consult the official `Python documentation `_ for details. +Install Python for your operating system. +On Windows and macOS this is usually necessary. +Most Linux distributions are coming with Python pre-installed. +Consult the official `Python documentation `_ for details. -You can install the Python binaries from `python.org `_. Alternatively on macOS, you can use the `homebrew `_ package manager. +You can install the Python binaries from `python.org `_. +Alternatively on macOS, you can use the `homebrew `_ package manager. .. code-block:: bash - $ brew install python3 + brew install python3 Adjust your path @@ -69,27 +73,27 @@ At the command line: .. code-block:: bash - $ python3 -m pip install --user cookiecutter + python3 -m pip install --user cookiecutter Or, if you do not have pip: .. code-block:: bash - $ easy_install --user cookiecutter + easy_install --user cookiecutter -Though, pip is recommended. +Though, pip is recommended, easy_install is deprecated. Or, if you are using conda, first add conda-forge to your channels: .. code-block:: bash - $ conda config --add channels conda-forge + conda config --add channels conda-forge Once the conda-forge channel has been enabled, cookiecutter can be installed with: .. code-block:: bash - $ conda install cookiecutter + conda install cookiecutter Alternate installations ----------------------- @@ -98,40 +102,40 @@ Alternate installations .. code-block:: bash - $ brew install cookiecutter + brew install cookiecutter **Pipx (Linux, OSX and Windows):** .. code-block:: bash - $ pipx install cookiecutter + pipx install cookiecutter -**Debian/Ubuntu:** -.. code-block:: bash - - $ sudo apt-get install cookiecutter +Upgrading +--------- -Upgrading from 0.6.4 to 0.7.0 or greater ----------------------------------------- +from 0.6.4 to 0.7.0 or greater +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -First, read :doc:`HISTORY` in detail. There are a lot of major -changes. The big ones are: +First, read :doc:`HISTORY` in detail. +There are a lot of major changes. +The big ones are: * Cookiecutter no longer deletes the cloned repo after generating a project. * Cloned repos are saved into `~/.cookiecutters/`. * You can optionally create a `~/.cookiecutterrc` config file. -Upgrade Cookiecutter either with easy_install: + +Or with pip: .. code-block:: bash - $ easy_install --upgrade cookiecutter + python3 -m pip install --upgrade cookiecutter -Or with pip: +Upgrade Cookiecutter either with easy_install (deprecated): .. code-block:: bash - $ python3 -m pip install --upgrade cookiecutter + easy_install --upgrade cookiecutter Then you should be good to go. diff --git a/docs/overview.rst b/docs/overview.rst index 0a823305b..6a1895614 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -2,10 +2,20 @@ Overview ======== +Cookiecutter takes a template provided as a directory structure with template-files. +Templates can be in located in the filesystem, as a ZIP-file or on a VCS-Server (Git/Hg) like GitHub. + +It reads a settings file and prompts the user interactivly wether to change the settings. + +Then it takes both and generates an output directory structure from it. + +Additional the template can provide code (Python or shell-script) to be executed before and after generation (pre-gen- and post-gen-hooks). + + Input ----- -This is the directory structure for a simple cookiecutter:: +This is a directory structure for a simple cookiecutter:: cookiecutter-something/ ├── {{ cookiecutter.project_name }}/ <--------- Project template @@ -17,9 +27,8 @@ This is the directory structure for a simple cookiecutter:: You must have: -* A `cookiecutter.json` file. -* A `{{ cookiecutter.project_name }}/` directory, where - `project_name` is defined in your `cookiecutter.json`. +- A ``cookiecutter.json`` file. +- A ``{{ cookiecutter.project_name }}/`` directory, where ``project_name`` is defined in your ``cookiecutter.json``. Beyond that, you can have whatever files/directories you want. diff --git a/docs/tutorials.rst b/docs/tutorials.rst deleted file mode 100644 index 16903235e..000000000 --- a/docs/tutorials.rst +++ /dev/null @@ -1,33 +0,0 @@ -==================== -Additional Tutorials -==================== - -Learn How to Use Cookiecutter ------------------------------ - -* :doc:`tutorial1` by `@audreyr`_ - - -Create Your Very Own Cookiecutter Project Template --------------------------------------------------- - -* :doc:`tutorial2` by `@audreyr`_ - -* `Project Templates Made Easy`_ by `@pydanny`_ - -* Cookiedozer Tutorials by `@hackebrot`_ - - * Part 1: `Create your own Cookiecutter template`_ - * Part 2: `Extending our Cookiecutter template`_ - * Part 3: `Wrapping up our Cookiecutter template`_ - - -.. _`Project Templates Made Easy`: http://www.pydanny.com/cookie-project-templates-made-easy.html - -.. _`Create your own Cookiecutter template`: https://raphael.codes/blog/create-your-own-cookiecutter-template/ -.. _`Extending our Cookiecutter template`: https://raphael.codes/blog/extending-our-cookiecutter-template/ -.. _`Wrapping up our Cookiecutter template`: https://raphael.codes/blog/wrapping-up-our-cookiecutter-template/ - -.. _`@audreyr`: https://github.com/audreyr -.. _`@pydanny`: https://github.com/pydanny -.. _`@hackebrot`: https://github.com/hackebrot diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst new file mode 100644 index 000000000..81e1b0dff --- /dev/null +++ b/docs/tutorials/index.rst @@ -0,0 +1,36 @@ +==================== +Tutorials +==================== + +Tutorials by `@audreyr`_ + +.. toctree:: + :maxdepth: 2 + + tutorial1 + tutorial2 + + +External Links +-------------- + +- `Learn the Basics of Cookiecutter by Creating a Cookiecutter`_ - first steps tutorial with example template by `@BruceEckel`_ +- `Project Templates Made Easy`_ by `@pydanny`_ +- Cookiedozer Tutorials by `@hackebrot`_ + + - Part 1: `Create your own Cookiecutter template`_ + - Part 2: `Extending our Cookiecutter template`_ + - Part 3: `Wrapping up our Cookiecutter template`_ + + +.. _`Learn the Basics of Cookiecutter by Creating a Cookiecutter`: https://github.com/BruceEckel/HelloCookieCutter1/blob/master/Readme.rst +.. _`Project Templates Made Easy`: http://www.pydanny.com/cookie-project-templates-made-easy.html + +.. _`Create your own Cookiecutter template`: https://raphael.codes/blog/create-your-own-cookiecutter-template/ +.. _`Extending our Cookiecutter template`: https://raphael.codes/blog/extending-our-cookiecutter-template/ +.. _`Wrapping up our Cookiecutter template`: https://raphael.codes/blog/wrapping-up-our-cookiecutter-template/ + +.. _`@audreyr`: https://github.com/audreyr +.. _`@pydanny`: https://github.com/pydanny +.. _`@hackebrot`: https://github.com/hackebrot +.. _`@BruceEckel`: https://github.com/BruceEckel diff --git a/docs/tutorial1.rst b/docs/tutorials/tutorial1.rst similarity index 68% rename from docs/tutorial1.rst rename to docs/tutorials/tutorial1.rst index 2659db8b2..0871ca696 100644 --- a/docs/tutorial1.rst +++ b/docs/tutorials/tutorial1.rst @@ -3,30 +3,27 @@ Getting to Know Cookiecutter ============================= .. note:: Before you begin, please install Cookiecutter 0.7.0 or higher. - Instructions are in :doc:`installation`. + Instructions are in :doc:`../installation`. -Cookiecutter is a tool for creating projects from *cookiecutters* (project -templates). +Cookiecutter is a tool for creating projects from *cookiecutters* (project templates). What exactly does this mean? Read on! Case Study: cookiecutter-pypackage ----------------------------------- -*cookiecutter-pypackage* is a cookiecutter template that creates the starter -boilerplate for a Python package. +*cookiecutter-pypackage* is a cookiecutter template that creates the starter boilerplate for a Python package. -.. note:: There are several variations of it, but for this tutorial we'll use - the original version at https://github.com/audreyr/cookiecutter-pypackage/. +.. note:: + There are several variations of it. + For this tutorial we'll use the original version at https://github.com/audreyr/cookiecutter-pypackage/. Step 1: Generate a Python Package Project ------------------------------------------ -Open your shell and cd into the directory where you'd like to create a starter -Python package project. +Open your shell and cd into the directory where you'd like to create a starter Python package project. -At the command line, run the cookiecutter command, passing in the link to -cookiecutter-pypackage's HTTPS clone URL like this: +At the command line, run the cookiecutter command, passing in the link to cookiecutter-pypackage's HTTPS clone URL like this: .. code-block:: bash @@ -35,18 +32,17 @@ cookiecutter-pypackage's HTTPS clone URL like this: Local Cloning of Project Template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -First, cookiecutter-pypackage gets cloned to `~/.cookiecutters/` (or equivalent -on Windows). Cookiecutter does this for you, so sit back and wait. +First, cookiecutter-pypackage gets cloned to `~/.cookiecutters/` (or equivalent on Windows). +Cookiecutter does this for you, so sit back and wait. Local Generation of Project ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When cloning is complete, you will be prompted to enter a bunch of values, such -as `full_name`, `email`, and `project_name`. Either enter your info, or simply -press return/enter to accept the default values. +When cloning is complete, you will be prompted to enter a bunch of values, such as `full_name`, `email`, and `project_name`. +Either enter your info, or simply press return/enter to accept the default values. -This info will be used to fill in the blanks for your project. For example, -your name and the year will be placed into the LICENSE file. +This info will be used to fill in the blanks for your project. +For example, your name and the year will be placed into the LICENSE file. Step 2: Explore What Got Generated ---------------------------------- @@ -58,8 +54,7 @@ In your current directory, you should see that a project got generated: $ ls boilerplate -Looking inside the `boilerplate/` (or directory corresponding to your `project_slug`) -directory, you should see something like this: +Looking inside the `boilerplate/` (or directory corresponding to your `project_slug`) directory, you should see something like this: .. code-block:: bash @@ -94,38 +89,38 @@ Notice how it was auto-populated with your (or my) name and email. Also take note of the fact that you are looking at a ReStructuredText file. Cookiecutter can generate a project with text files of any type. -Great, you just generated a skeleton Python package. How did that work? +Great, you just generated a skeleton Python package. +How did that work? Step 3: Observe How It Was Generated ------------------------------------ -Let's take a look at cookiecutter-pypackage together. Open https://github.com/audreyr/cookiecutter-pypackage in a new browser window. +Let's take a look at cookiecutter-pypackage together. +Open https://github.com/audreyr/cookiecutter-pypackage in a new browser window. {{ cookiecutter.project_slug }} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Find the directory called `{{ cookiecutter.project_slug }}`. Click on it. Observe -the files inside of it. You should see that this directory and its contents -corresponds to the project that you just generated. +Find the directory called `{{ cookiecutter.project_slug }}`. +Click on it. +Observe the files inside of it. +You should see that this directory and its contents corresponds to the project that you just generated. This happens in `find.py`, where the `find_template()` method looks for the first jinja-like directory name that starts with `cookiecutter`. AUTHORS.rst ~~~~~~~~~~~ -Look at the raw version of `{{ cookiecutter.project_slug }}/AUTHORS.rst`, at -https://raw.github.com/audreyr/cookiecutter-pypackage/master/%7B%7Bcookiecutter.project_slug%7D%7D/AUTHORS.rst. +Look at the raw version of `{{ cookiecutter.project_slug }}/AUTHORS.rst`, at https://raw.github.com/audreyr/cookiecutter-pypackage/master/%7B%7Bcookiecutter.project_slug%7D%7D/AUTHORS.rst. Observe how it corresponds to the `AUTHORS.rst` file that you generated. cookiecutter.json ~~~~~~~~~~~~~~~~~ -Now navigate back up to `cookiecutter-pypackage/` and look at the -`cookiecutter.json` file. +Now navigate back up to `cookiecutter-pypackage/` and look at the `cookiecutter.json` file. -You should see JSON that corresponds to the prompts and default values shown -earlier during project generation: +You should see JSON that corresponds to the prompts and default values shown earlier during project generation: .. code-block:: json @@ -147,13 +142,11 @@ earlier during project generation: Questions? ---------- -If anything needs better explanation, please take a moment to file an issue at https://github.com/audreyr/cookiecutter/issues with what could be improved -about this tutorial. +If anything needs better explanation, please take a moment to file an issue at https://github.com/audreyr/cookiecutter/issues with what could be improved about this tutorial. Summary ------- -You have learned how to use Cookiecutter to generate your first project from a -cookiecutter project template. +You have learned how to use Cookiecutter to generate your first project from a cookiecutter project template. -In Tutorial 2, you'll see how to create cookiecutters of your own, from scratch. +In tutorial 2 (:ref:`tutorial2`), you'll see how to create cookiecutters of your own, from scratch. diff --git a/docs/tutorial2.rst b/docs/tutorials/tutorial2.rst similarity index 68% rename from docs/tutorial2.rst rename to docs/tutorials/tutorial2.rst index 830206788..53fcc1d21 100644 --- a/docs/tutorial2.rst +++ b/docs/tutorials/tutorial2.rst @@ -1,3 +1,5 @@ +.. _tutorial2: + ================================== Create a Cookiecutter From Scratch ================================== @@ -5,8 +7,7 @@ Create a Cookiecutter From Scratch Step 1: Name Your Cookiecutter ------------------------------ -In this tutorial, we are creating *cookiecutter-website-simple*, a cookiecutter -for generating simple, bare-bones websites. +In this tutorial, we are creating *cookiecutter-website-simple*, a cookiecutter for generating simple, bare-bones websites. Create the directory for your cookiecutter and cd into it: @@ -18,15 +19,13 @@ Create the directory for your cookiecutter and cd into it: Step 2: Create `project_slug` Directory --------------------------------------- -Create a directory called `{{ cookiecutter.project_slug }}`. +Create a directory called ``{{ cookiecutter.project_slug }}``. -This value will be replaced with the repo name of projects that you generate -from this cookiecutter. +This value will be replaced with the repo name of projects that you generate from this cookiecutter. Step 3: Create Files -------------------- -Inside of `{{ cookiecutter.project_slug }}`, create `index.html`, `site.css`, and -`site.js`. +Inside of ``{{ cookiecutter.project_slug }}``, create ``index.html``, ``site.css``, and ``site.js``. To be continued... diff --git a/setup.py b/setup.py index d703c3c29..9cb220978 100644 --- a/setup.py +++ b/setup.py @@ -2,7 +2,7 @@ """cookiecutter distutils configuration.""" from setuptools import setup -version = "2.0.0" +version = "2.0.3.dev0" with open('README.md', encoding='utf-8') as readme_file: readme = readme_file.read() @@ -34,7 +34,7 @@ package_dir={'cookiecutter': 'cookiecutter'}, entry_points={'console_scripts': ['cookiecutter = cookiecutter.__main__:main']}, include_package_data=True, - python_requires='>=3.6', + python_requires='>=3.7', install_requires=requirements, license='BSD', zip_safe=False, @@ -46,10 +46,10 @@ "License :: OSI Approved :: BSD License", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3", - "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", "Programming Language :: Python :: Implementation :: CPython", "Programming Language :: Python :: Implementation :: PyPy", "Programming Language :: Python",