site-support/README.md

# DTU Python Support
This is the repository containing the "DTU Python Support" book.
See it live: https://pysupport.timesigned.com.

## Getting Started
We've automated all the gnarly steps between beautiful `*.md` source files, and a real, running website.

You'll need to have the following commands available:
- `git`: <https://git-scm.com/>
- `python`: Newer than `3.9`.
- `podman`: <https://podman.io/>
- `pre-commit`: <https://pre-commit.com/>
- `echo "I am not afraid of the terminal!"`

Once that's set, go ahead and grab (`clone`, in `git` terms) this repo:
```bash
git clone https://git.sofus.io/python-support/site-support.git
cd site-support
```

Now, you can view the book in your local browser:
```bash
./run.py app
## Now, navigate to http://localhost:8787 in your browser.
## CTRL+C to exit.
```

Run this whenever you want to preview any changes you made to `src/*.md` files!



# Structure of the Book
The book is structured to minimize technical wonk, and let you *focus on writing*.
This is made possible due to `mdbook`, this project avoids a lot of the technical boiler

## Easy Overview / ToC / Menu: `src/SUMMARY.md`
The beating heart of the book is [`src/SUMMARY.md`](./src/SUMMARY.md).
The headings, bullet nesting, and links result in the side-menu.


## Written in Markdown: A Gentler Take on Text
"Markdown" is text for humans. That's it!

This **entire book** is written in **100% normal** "Markdown".
The *only* filetype in `src/` is `*.md`.

All `.md` files can be opened in *any text editor*.
No, not Word; think Notepad, vim, VSCodium!

But what does it look like? Ya know, `.md` files?

```markdown
It looks pretty normal, honestly.
You can **bold**, *italic*, and even write `cool_l33t_code`!

You'll need a [text editor of some kind](https://neovim.io/), of course.
But you'll find that super quick; after all, you are:
- Cool
- Knowledgeable
- Awesome
```

With a little bit of extension magic, like the built-in MermaidJS, you can even impress your cat!
```mermaid
journey
    title Learning to Use site-support: A User Journey
    section Utter Confusion
      Find the Repo: 1: You, A Rus, A Kitten
      Clone the Repo: 3: You, A Kitten
      Notice it's all .md: 5: You
    section Fun and Games
      Discover ./run.py app: 7: You
      Change stuff: 9: You
```



# Contributing
Let's say you've made some cool changes, and you want to propose they go into the book.
First of all, thank you!
But, how do?

At this point, you'll need to know a bit of `git`.
Incidentally, the book contains a quick guide at [`src/basics/collaboration/git`](./src/basics/collaboration/git)!
This git-powered puzzle game is also a surprisingly effective teacher: <https://learngitbranching.js.org/>

Armed with this knowledge, make a branch **within the repo folder**:
```bash
git checkout -b <branch_name>
git branch
```
You're now on a new branch, which belongs only to you!

Now, commit your changes. Remember to use [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) format for your commit message.
For example:
```bash
git add -A
git status ## Always review your changes!
git commit -m "feat: New page!"
```
That's it! Give it a `git push`.

All that's left is to start a [Pull Request](https://git.sofus.io/python-support/site-support/pulls), and wait for someone on the team to examine your contribution.

When several people collaborate, the workflow might end up looking something like this:
```mermaid
gitGraph
    commit
    commit tag: "v0.1.0"
    branch bobs-cool-new-feature
    branch jills-hotfix
    checkout bobs-cool-new-feature
    commit
    commit
    commit
    checkout jills-hotfix
    commit
    commit
    checkout main
    merge  jills-hotfix tag: "v0.1.1"
    merge bobs-cool-new-feature  tag: "v0.2.0"
```



# Conclusion
You should have everything you need to get started.
If anything is still confusing, don't hesitate to report an [Issue](https://git.sofus.io/python-support/site-support/issues)!