From 890ad2bdefac0c1a59e6413b80de73b7f83debf2 Mon Sep 17 00:00:00 2001 From: "Jens W. Klein" Date: Mon, 30 May 2022 12:28:09 +0200 Subject: [PATCH] Documnetation overhaul 2 --- AUTHORS.md | 1 + CODE_OF_CONDUCT.md | 5 +- CONTRIBUTING.md | 275 +++++++++++++++++++++++------------------- README.md | 50 ++++---- docs/cookiecutter.rst | 7 +- docs/index.rst | 2 +- docs/installation.rst | 18 +-- docs/overview.rst | 5 +- 8 files changed, 190 insertions(+), 173 deletions(-) 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/README.md b/README.md index 493f63cc4..38de8e205 100644 --- a/README.md +++ b/README.md @@ -8,8 +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) @@ -149,9 +148,10 @@ You are almost not limited in topics amount, use it! 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. @@ -164,8 +164,8 @@ 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. +- 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). @@ -177,8 +177,8 @@ Development on Cookiecutter is community-driven: - 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). @@ -186,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/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 1a391b521..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 ------ diff --git a/docs/installation.rst b/docs/installation.rst index e4084ab81..068c6d9d9 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -22,7 +22,7 @@ Alternatively on macOS, you can use the `homebrew `_ package ma .. code-block:: bash - $ brew install python3 + brew install python3 Adjust your path @@ -73,13 +73,13 @@ 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, easy_install is deprecated. @@ -87,13 +87,13 @@ 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 ----------------------- @@ -102,13 +102,13 @@ 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 Upgrading @@ -130,12 +130,12 @@ Or with pip: .. code-block:: bash - $ python3 -m pip install --upgrade cookiecutter + python3 -m pip install --upgrade cookiecutter Upgrade Cookiecutter either with easy_install (deprecated): .. code-block:: bash - $ easy_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 6b8e029ee..6a1895614 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -27,9 +27,8 @@ This is a 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.