Skip to content

Commit 88962f4

Browse files
lwjohnst86lwjohnst86
committed
refactor: 🚚 moved file explanation into CONTRIBUTING, not README
1 parent c8f2e6d commit 88962f4

2 files changed

Lines changed: 95 additions & 60 deletions

File tree

‎template/CONTRIBUTING.md.jinja‎

Lines changed: 64 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ so is at various states of completion.
1919
To contribute to `{{ github_repo }}`, you first need to install
2020
[uv](https://docs.astral.sh/uv/) and
2121
[justfile](https://just.systems/man/en/packages.html). We use uv and
22-
justfile to manage our project, such as to run checks and test the
22+
justfile to manage our package, such as to run checks and test the
2323
template. Both the uv and justfile websites have a more detailed guide
2424
on using uv, but below are some simple instructions to get you started.
2525

@@ -40,7 +40,7 @@ just
4040
```
4141

4242
As you contribute, make sure your changes will pass our tests by opening
43-
a terminal so that the working directory is the root of this project's
43+
a terminal so that the working directory is the root of this package's
4444
repository and running:
4545

4646
``` bash
@@ -53,7 +53,67 @@ as Git messages. Using this convention allows us to be able to
5353
automatically create a release based on the commit message by using
5454
[Commitizen](https://decisions.seedcase-project.org/why-semantic-release-with-commitizen/).
5555
If you don't use Conventional Commits when making a commit, we will
56-
revise the pull request title to follow that format, as we use [squash
57-
merges](https://git-scm.com/docs/git-merge) when merging pull requests,
56+
revise the pull request title to follow that format, as we use squash
57+
merges when merging pull requests,
5858
so all other commits in the pull request will be squashed into one
5959
commit.
60+
61+
## :file_folder: Explanation of files and folders
62+
63+
This list describes the default files that are included in the template
64+
as well as explains a bit more about them and what they are used for.
65+
66+
- `.github/`: Contains GitHub-specific files, such as issue and pull
67+
request templates, workflows,
68+
[dependabot](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/dependabot-quickstart-guide)
69+
configuration, pull request templates, and a
70+
[CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)
71+
file.
72+
- `tools/vulture-allowlist.py`: List of variables that shouldn't be
73+
flagged by [Vulture](https://github.com/jendrikseipp/vulture) as
74+
unused.
75+
- `tools/get-contributors.sh`: Script to get list of package
76+
contributors.
77+
- `tests/`: Test files for the package.
78+
- `src/`: Source code for the package.
79+
- `docs/`: Documentation about using and developing the Python package.
80+
- `.config/`: Contains configuration files for various tools used in the package,
81+
such as:
82+
- `quartodoc.py`: Custom
83+
[`quartodoc`](https://machow.github.io/quartodoc/) renderer.
84+
- `mypy.ini`: [`mypy`](https://mypy.readthedocs.io/en/stable/)
85+
configuration file for type checking Python code.
86+
- `ruff.toml`: [Ruff](https://docs.astral.sh/ruff/) configuration file
87+
for linting and formatting Python code.
88+
- `rumdl.toml`: [rumdl](https://rumdl.dev/) configuration file for
89+
formatting Markdown files so that they are standardized and consistent
90+
{%- if for_seedcase %}
91+
- `cog.toml`: [Cocogitto](https://docs.cocogitto.io) configuration file
92+
for managing versions.
93+
- `cliff.toml`: [git-cliff](https://git-cliff.org) configuration file for
94+
creating the changelog.
95+
{%- endif %}
96+
- `.copier-answers.yml`: Contains the answers you gave when copying the
97+
package from the template.
98+
**You should not modify this file directly.**
99+
- `.pre-commit-config.yaml`: [Pre-commit](https://pre-commit.com/)
100+
configuration file for managing and running checks before each commit.
101+
- `.typos.toml`: [typos](https://github.com/crate-ci/typos) spell
102+
checker configuration file.
103+
- `justfile`: [`just`](https://just.systems/man/en/) configuration file
104+
for scripting package tasks.
105+
- `.editorconfig`: Editor configuration file for
106+
[EditorConfig](https://editorconfig.org/) to maintain consistent
107+
coding styles across different editors and IDEs.
108+
- `CHANGELOG.md`: Changelog file for tracking changes in the package.
109+
- `CITATION.cff`: Structured citation metadata for your package.
110+
- `CONTRIBUTING.md`: Guidelines for contributing to the package.
111+
- `_metadata.yml`: Quarto metadata file for the website, including
112+
information about the package, such as the titles and GitHub names.
113+
- `_quarto.yml`: Quarto configuration file for the website, including
114+
settings for the website, such as the theme, navigation, and other
115+
options.
116+
- `pyproject.toml`: Main Python package configuration file defining
117+
metadata and dependencies.
118+
- `uv.lock`: Lockfile used by [`uv`](https://docs.astral.sh/uv/) to
119+
record exact versions of installed dependencies.

‎template/README.qmd‎

Lines changed: 31 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,74 +1,28 @@
11
---
22
format: gfm
3+
execute:
4+
echo: false
35
metadata-files:
46
- _metadata.yml
57
---
68

7-
# {{< meta gh.repo >}}: TODO add more to title
9+
# {{< meta tagline >}}
810

911
{{< include /docs/includes/_badges.qmd >}}
1012

11-
<!-- TODO: Add description of project -->
13+
<!-- TODO: Add description of package -->
14+
15+
Check out our [website]({{< meta links.site >}}) for more information,
16+
such as the features it provides and a
17+
[guide]({{< meta links.site >}}/docs/guide) to using the package. For a
18+
list of changes, see our [changelog](CHANGELOG.md) page.
1219

1320
::: callout-tip
1421
This Python package was generated from the
15-
[`template-python-package`](https://github.com/seedcase-project/template-python-package)
22+
[Template Python Package](https://github.com/seedcase-project/template-python-package)
1623
Seedcase template :tada:
1724
:::
1825

19-
## Project files and folders
20-
21-
- `.github/`: Contains GitHub-specific files, such as issue and pull
22-
request templates, workflows,
23-
[dependabot](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/dependabot-quickstart-guide)
24-
configuration, pull request templates, and a
25-
[CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)
26-
file.
27-
- `tools/vulture-allowlist.py`: List of variables that shouldn't be
28-
flagged by [Vulture](https://github.com/jendrikseipp/vulture) as
29-
unused.
30-
- `tools/get-contributors.sh`: Script to get list of project
31-
contributors.
32-
- `tests/`: Test files for the package.
33-
- `src/`: Source code for the package.
34-
- `docs/`: Documentation about using and developing the Python package.
35-
- `_renderer.py`: Custom
36-
[`quartodoc`](https://machow.github.io/quartodoc/) renderer.
37-
- `pytest.ini`: Pytest configuration file.
38-
- `mypy.ini`: [`mypy`](https://mypy.readthedocs.io/en/stable/)
39-
configuration file for type checking Python code.
40-
- `.copier-answers.yml`: Contains the answers you gave when copying the
41-
project from the template.
42-
**You should not modify this file directly.**
43-
- `.cz.toml`:
44-
[Commitizen](https://commitizen-tools.github.io/commitizen/)
45-
configuration file for managing versions and changelogs.
46-
- `.pre-commit-config.yaml`: [Pre-commit](https://pre-commit.com/)
47-
configuration file for managing and running checks before each commit.
48-
- `.typos.toml`: [typos](https://github.com/crate-ci/typos) spell
49-
checker configuration file.
50-
- `justfile`: [`just`](https://just.systems/man/en/) configuration file
51-
for scripting project tasks.
52-
- `.editorconfig`: Editor configuration file for
53-
[EditorConfig](https://editorconfig.org/) to maintain consistent
54-
coding styles across different editors and IDEs.
55-
- `CHANGELOG.md`: Changelog file for tracking changes in the project.
56-
- `CITATION.cff`: Structured citation metadata for your project.
57-
- `CONTRIBUTING.md`: Guidelines for contributing to the project.
58-
- `_metadata.yml`: Quarto metadata file for the website, including
59-
information about the project, such as the titles and GitHub names.
60-
- `pyproject.toml`: Main Python project configuration file defining
61-
metadata and dependencies.
62-
- `_quarto.yml`: Quarto configuration file for the website, including
63-
settings for the website, such as the theme, navigation, and other
64-
options.
65-
- `ruff.toml`: [Ruff](https://docs.astral.sh/ruff/) configuration file
66-
for linting and formatting Python code.
67-
- `uv.lock`: Lockfile used by [`uv`](https://docs.astral.sh/uv/) to
68-
record exact versions of installed dependencies.
69-
- `.rumdl.toml`: [rumdl](https://rumdl.dev/) configuration file for
70-
formatting Markdown files so that they are standardized and consistent
71-
7226
## Contributing
7327

7428
Check out our [contributing document](CONTRIBUTING.md) for information
@@ -79,10 +33,31 @@ Please note that this project is released with a
7933
[Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in
8034
this project you agree to abide by its terms.
8135

36+
::: content-hidden
37+
### Contributors
38+
39+
{{< include /docs/includes/_contributors.qmd >}}
40+
:::
41+
8242
## Licensing
8343

8444
This project is licensed under the [MIT License](LICENSE.md).
8545

8646
## Changelog
8747

8848
For a list of changes, see our [changelog](CHANGELOG.md) page.
49+
50+
## Citing
51+
52+
If you use this package in your work, please cite it as follows:
53+
54+
```{python}
55+
#| output: asis
56+
!uvx --quiet cffconvert --format apalike
57+
```
58+
59+
Or as a BibTeX entry:
60+
61+
```{python}
62+
!uvx --quiet cffconvert --format bibtex
63+
```

0 commit comments

Comments
 (0)