Creating your first project#

If you followed the steps outlined in Getting Started, you are now presented with a couple of questions about your new project:

Question	Answers
What is the name of your project?	Title case string, can contain spaces
What is the name of your Python package?	Lowercase string, can contain underscores
Use pre-commit to run checks on each commit?	Yes (default) No
Use bumpversion to manage semantic version across multiple files?	Yes No (default)
Which documentation tool do you want to use?	Material for MkDocs (default) Sphinx None
Which documentation template do you want to use?	Fraunhofer IIS Sphinx Template None (default)
Which platform will your project be hosted on?	GitHub (default) FHG Gitlab IIS Gitlab
User name (the one you used with your hosted git provider)
Email address of the author
URL of the remote repository	SSH URL to your remote repository
Name of the initial git branch that will be created	Lowercase string, can contain dashes Examples: `main`, `master`, `dev`

Let's look at them one by one and figure out, what you should choose or how to find the information the template asks for.

Project Name#

The project name will be used to propose a suitable package name and Remote Url. It is also repeated in multiple places (Python package configuration, documentation, etc.).

Package Name#

This is the name of your Python package. As such, it will be used as the name of the directory containing your code. All imports of your package start with this name.

Example: If you choose sample_project as your package name, your code files would be created in

./
├── src
│   └── sample_project
│       ├── __init__.py
│       ├── __main__.py
│       └── some_module.py
├── pyproject.toml
└── ...

and your imports would look like this:

from sample_project import some_module

You might want to consult PEP 423 – Naming conventions and recipes related to packaging for guidance on Python package name conventions.

The cli command included with this template will be named after your package, only with dashes instead of underscores. Following the example above, your cli would then be available as

$ sample-project --help

If you ever want to publish your Python package to PyPI, the package name has to be unique to be accepted there.

Finally, the package name is repeated across multiple configuration and documentation files.

pre-commit#

pre-commit is a tool that makes configuring git hooks a lot easier.

This template uses pre-commit hooks to ensure, all changes match the expected formatting and style. Additionally, running linters at this stage can prevent committing something that contains obvious issues.

Most formatters and some linters are able to fix issues automatically. So you can simply review the changes those tools made, stage them and commit again.

Bumpversion#

If you want to version your project, bumpversion provides an easy way to increase version numbers across multiple files.

It integrates with git and helps with your release workflow by automating version bump, commit and tag creation. Used correctly, releasing a new version of your project can be done with a single command.

It also helps to follow semantic versioning guidelines when increasing your version numbers.

Docs#

Documentation is an important part of any project.

So far, this template supports two documentation tools: MkDocs and Sphinx.

MkDocs is a great documentation tool built around Markdown. It is easy to use and produces a great looking documentation website with minimal overhead and configuration.

Sphinx is a powerful tool for documentation written in Markdown or reStructuredText. With the myst_parser it is now (almost) possible to rely on Markdown only. Choose this if you want to publish your documentation in multiple formats (e.g. PDF, HTML, ePub, ...).

If you are not sure which one to use, simply go with the default 😉.

Docs Template#

See Fraunhofer IIS Sphinx Template.

Remote#

This template provides a CI configuration for either GitHub (Github Actions) or GitLab (Gitlab CI).

Also, the link to your documentation depends on which remote you choose.

If you want to push your project to multiple remotes, you can add them later.

User Name#

This is the user name you are using with the remote provider you provided in the previous question.

Together with remote, it will be used to suggest a remote url for your project.

Email Address#

This is the email address for the author of the project.

Remote Url#

Apart from configuring the git remote for you, the remote URL is required to determine other values, such as

Links in your README and CHANGELOG files
Links to your documentation
Link to your repository from your documentation
...

If you did not create your remote repository yet (i.e. new project at GitHub or Gitlab), this might be a good time to do so.

Create empty repository

Do not initialize your remote project with a LICENSE or README file. This will let you push your initial commit without merge or rebase.

GitlabGitHub

The SSH URL to your Gitlab repository can be found under the Clone dropdown (screenshot taken 23.08.23)

The SSH URL to your GitHub repository can be found under the <> Code dropdown menu (screenshot taken 23.08.23)

Default Branch#

Name of the initial branch of your new project.

This branch traditionally was called master, but is more often called main now.

Congrats 🎉 You just created your first project!

Head over to Next Steps to find out what you should do now.

🤓 Pro tip: Simply press . to continue to the next page...