129 lines
3.9 KiB
Markdown
129 lines
3.9 KiB
Markdown
# 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)!
|