3.9 KiB

Raw Blame History

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:

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!

3.9 KiB Raw Blame History