Sofus Albert Høgsbro Rose 2f29ec8de9 | ||
---|---|---|
src | ||
.dockerignore | ||
.gitignore | ||
.pre-commit-config.yaml | ||
Dockerfile | ||
LICENSE | ||
README.md | ||
book.toml | ||
run.py |
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 than3.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:
git clone https://git.sofus.io/python-support/site-support.git
cd site-support
Now, you can view the book in your local browser:
./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
.
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?
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!
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
!
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:
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 format for your commit message. For example:
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, and wait for someone on the team to examine your contribution.
When several people collaborate, the workflow might end up looking something like this:
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!