https://github.com/withprecedent/ursula
Cookiecutter template for academic writing projects
https://github.com/withprecedent/ursula
Last synced: 2 months ago
JSON representation
Cookiecutter template for academic writing projects
- Host: GitHub
- URL: https://github.com/withprecedent/ursula
- Owner: WithPrecedent
- License: other
- Created: 2024-06-03T19:51:27.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-30T17:14:32.000Z (over 1 year ago)
- Last Synced: 2025-01-16T01:16:56.085Z (over 1 year ago)
- Language: Python
- Size: 1.14 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# ursula
“*A writer is a person who cares what words mean, what they say, how they say it. Writers know words are their way towards truth and freedom, and so they use them with care, with thought, with fear, with delight. By using words well they strengthen their souls. Story-tellers and poets spend their lives learning that skill and art of using words well. And their words make the souls of their readers stronger, brighter, deeper.*”
― Ursula K. Le Guin
| | |
| --- | --- |
| Version | [](https://pypi.org/project/ursula/) [](https://github.com/WithPrecedent/ursula/releases)
| Status | [](https://www.repostatus.org/#active) [](https://pypi.org/project/ursula/)
| Documentation | [](https://withprecedent.github.io/ursula)
| Compatibility | [](https://pypi.python.org/pypi/ursula/) [](https://www.linux.org/) [](https://www.apple.com/macos/) [](https://www.microsoft.com/en-us/windows?r=1)
| Stats | [](https://pypi.org/project/ursula) [](https://github.com/withprecedent/ursula/stargazers) [](https://github.com/withprecedent/ursula/graphs/contributors) [](https://github.com/withprecedent/ursula/graphs/contributors) [](https://github.com/withprecedent/ursula/forks) |
| | |
## What is ursula?
`ursula` is an easy-to-use `cookiecutter` template for academic markdown writing
projects that may include code. To see an example repository using this
template, check out
[`ursula_demo`](https://github.com/withprecedent/ursula_demo). The primary goal of
`ursula` is to store all of your materials for a project (writing, code,
presentations, data, images, media, etc.) in one organized location. Any given
project need not use all of the features and aspects of `ursula`, but they are
always there in case a project expands or changes direction.
Out of the box, `ursula` is designed for projects that:
* Write scholarship and make slides using
[](https://www.markdownguide.org/)
(any flavor, including [](https://quarto.org/))
* Plan to host your project on [](https://www.github.com/)
* May include [](https://www.python.org/) code[^1]
* Want replication and/or usage documentation automatically created using [](https://www.mkdocs.org/)
with the [](https://squidfunk.github.io/mkdocs-material/) theme
on [](https://withprecedent.github.io/ursula)
## Why use ursula?
`ursula` is built on top of my general-use `Python` template: [`snickerdoodle`](https://www.github.com/WithPrecedent/snickerdoodle). You
can read the `readme` for that template to understand its advantages versus
other templates. What `ursula` adds is support for academic writing projects.
This may include articles or books. Presentation slides and notes are also
stored and can use the same resources (images, tables, graphs, etc.) as the
publication.
### Tools
If you include `Python` code in your project, `ursula` includes these modern, stable tools for package construction and
management that do not require any external services or costs:
* Dependency management: [](https://PDM.fming.dev) and [](https://github.com/dependabot)
* Testing: [](https://github.com/TezRomacH/python-package-template/blob/master/.pre-commit-config.yaml)
* CI/CD: [](https://github.com/features/actions)
* Code style:
[](https://github.com/astral-sh/Ruff),
[](https://github.com/TezRomacH/python-package-template/blob/master/.pre-commit-config.yaml),
and [](https://editorconfig.org/)
### Options
In addition to the included tools above, `ursula` includes several
options in the `cookiecutter` questionnaire that can be automatically applied
as part of the templating process:
* Badge style: [](https://www.shields.io/),
[](https://www.shields.io/),
[](https://www.shields.io/),
[](https://www.shields.io/),
or [](https://www.shields.io/)
* Push an [initial commit](https://github.com/WithPrecedent/ursula_demo) to GitHub
* Build and deploy [basic documentation](https://withprecedent.github.io/ursula_demo/) to GitHub Pages
* Create a `Python` virtual environment in the repository's ".venv" Folder
## Getting started
### Setup
If you are new to `cookiecutter` or simply want to guarantee that the created repository works as intended, follow the instructions in the [`ursula` tutorial](https://withprecedent.github.io/ursula/tutorial/).
If you are familiar with `cookiecutter` templates, you can go about the
normal construction process. However, if you do not select the optional
automatic setup features in the questionnaire, you should follow the instructions
for manually setting up your [virtual
environment](https://withprecedent.github.io/ursula/tutorial/#Create-Virtual-Environment)
and [deploying your
documentation](https://withprecedent.github.io/ursula/tutorial/#Deploy-Documentation)
in the [`ursula`
tutorial](https://withprecedent.github.io/ursula/tutorial/). It is
especially important to follow the document deployment process for your initial deployment - after that GitHub Actions will automatically update and redeploy the
documentation (and you need not use the manual process again).
### Usage
After your repository is created, you can start coding right away. Every push to GitHub will run any tests in the "tests" folder,
deploy documentation to GitHub Pages, and apply `ruff` for linting and
formatting. For more information about the following topics, just click on the
corresponding hyperlink.
* [Formatting and Linting](https://withprecedent.github.io/ursula/advanced/#formatting-and-linting)
* [GitHub Actions](https://withprecedent.github.io/ursula/advanced/#github-actions)
* [Publishing](https://withprecedent.github.io/ursula/advanced/#publishing)
* [Repository Layout](https://withprecedent.github.io/ursula/advanced/#repository-layout)
* [Versioning](https://withprecedent.github.io/ursula/advanced/#versioning)
## Contributing
Contributors are always welcome and should find `ursula` easy to work
with. The template is highly documented so that users and developers can adapt
or extend`ursula` to work with their projects. So, forking and creating
different template spins is encouraged. If you want to contribute directly to
the project, feel free to grab an [issue](https://github.com/WithPrecedent/ursula/issues) to work on
or make a suggested improvement. If you wish to contribute, please read the
[Contribution Guide](./contributing.md) and [Code of
Conduct](./code_of_conduct.md).
## Similar Projects
These are other `cookiecutter` templates using `pdm` as their dependency manager:
* [cookiecutter-docker-python-pdm](https://github.com/mnako/cookiecutter-docker-python-pdm): uses Docker and `black`.
* [cookie](https://github.com/chris-santiago/cookie): uses `mkdocs` and GitHub Actions, but also adds `conda`, `nox`, `black`, and `pyright`.
If you are interested in going beyond `cookiecutter` (or its forks),
[`copier`](https://github.com/copier-org/copier) is a powerful, newer templating package
and there is a great template that incorporates
several of the tools used in `ursula`:
* [copier-pdm](https://github.com/pdm-project/copier-pdm): includes, among other
tools, `pdm`,
`mkdocs`, and `ruff`.
## Acknowledgements
I'd also like to extend a special thanks to [pawamoy](https://github.com/pawamoy) whose excellent `pdm` and `mkdocs` extensions and utlities are incorporated into `ursula`. Some of the scripts, documentation, configuration files, and other CI code were all adapted from pawamoy's repositories.
I would also like to thank the University of Kansas School of Law for tolerating and supporting this law professor's coding efforts, an endeavor which is well outside the typical scholarly activities in the discipline.
## License
[](https://opensource.org/licenses/Apache-2.0)
[^1]: Contributions to add support for other programming languages are welcome.