Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add some reference docs on all the cookiecutter options #296

Closed
dstansby opened this issue Feb 6, 2024 · 6 comments · Fixed by #380
Closed

Add some reference docs on all the cookiecutter options #296

dstansby opened this issue Feb 6, 2024 · 6 comments · Fixed by #380
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@dstansby
Copy link
Member

dstansby commented Feb 6, 2024

Which Section of the Documentation Needs Improving?

It's wasn't clear from just the cookiecutter command line what initialise_git_repository does. In particular, does it initialise the repo locally or put it on GitHub? Or neither? In general it would be good to have some reference docs on what each of the cookiecutter optiolns is used for or does.

What Can be Improved About This Section

I think some reference documentation on what each of the cookicutter options means/is used for would be nice.

How to Improve This Section

No response

@dstansby dstansby added the documentation Improvements or additions to documentation label Feb 6, 2024
@samcunliffe samcunliffe changed the title [DOCS]: Not clear that initialise_git_repository creates a new GitHub repository \Not clear that initialise_git_repository creates a new GitHub repository Feb 6, 2024
@samcunliffe samcunliffe changed the title \Not clear that initialise_git_repository creates a new GitHub repository Not clear that initialise_git_repository creates a new GitHub repository Feb 6, 2024
@paddyroddy
Copy link
Member

It doesn't create a GitHub repository! I decided against that as too many nuances. It does things like recommending the GitHub CLI call, or just point to the documentation. Have another look at the hook.

@dstansby
Copy link
Member Author

dstansby commented Feb 6, 2024

Woops, I got confused. Either way it would be nice to have some reference documentation (even if it's short) about each of the options in the cookiecutter template explaining what they're used for, or what they do (which would have saved my confusion 😄 ).

@dstansby dstansby changed the title Not clear that initialise_git_repository creates a new GitHub repository Add some reference docs on all the cookiecutter options Feb 6, 2024
@dstansby
Copy link
Member Author

dstansby commented Feb 6, 2024

I updated the title and body of the issue to reflect the comment above ☝️

@paddyroddy
Copy link
Member

Yeah, I like that idea

@samcunliffe
Copy link
Member

Should the options docs just go in the body of README.md?

Perhaps in a <details> (I do love me a details).

<details><summary>Click to see more information about the questions...</summary>

* `github_owner`: either your GitHub username or the name of the GitHub organisation you're creating the repository under.
* `initialise_git_repository`: runs `git init`... insert nuance here.

<details>

@matt-graham
Copy link
Collaborator

matt-graham commented Feb 13, 2024

As an alternative or complement to having the options documented separately in the README or similar, cookiecutter supports having human-readable prompts in place of the variable names which would at least allow us to decouple the variable names and what is shown to the user.

matt-graham added a commit that referenced this issue Jun 5, 2024
Fixes #296 and fixes #305 

Adds longer human-readable prompts for all cookiecutter template options
using the `prompts` field in `cookiecutter.json` (we already had a
prompt for `deploy_docs_to_github_pages` option from #319).

---------

Co-authored-by: David Stansby <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants