From d5cea0ce8ef70bde1fd04e5e7dacc1a71bdf20ae Mon Sep 17 00:00:00 2001 From: zkldi <20380519+zkldi@users.noreply.github.com> Date: Sat, 13 Aug 2022 01:57:59 +0100 Subject: [PATCH] fix: touchup docker stuffs --- docs/docs/contributing/components.md | 2 +- .../contributing/components/documentation.md | 2 +- docs/docs/contributing/setup.md | 38 +++++++++++---- docs/docs/contributing/tools/vscode.md | 48 +++++++++++++++++++ docs/mkdocs.yml | 1 + 5 files changed, 81 insertions(+), 10 deletions(-) create mode 100644 docs/docs/contributing/tools/vscode.md diff --git a/docs/docs/contributing/components.md b/docs/docs/contributing/components.md index 697b5f7fd..1a719b233 100644 --- a/docs/docs/contributing/components.md +++ b/docs/docs/contributing/components.md @@ -8,7 +8,7 @@ All of them have their own things going on, so this page has all the guides for If you're already very familiar with `git`, the terminal, `node` and JSON, and care more about Tachi specific stuff (how to get the components running, what our architecture looks like), you should skip over that stuff in each guide. -We maintain these guides so that people with knowledge about how to improve Tachi can help out, regardless of their skill level! As such, not all of the information will be of use to you - Skip over the easy bits. +We maintain these guides so that people with knowledge about how to improve Tachi can help out, regardless of their skill level! As such, not all of the information will be of use to you - Skip over the tooling explanations. ## What can I contribute to? diff --git a/docs/docs/contributing/components/documentation.md b/docs/docs/contributing/components/documentation.md index b8d9dd1ca..8822d9e42 100644 --- a/docs/docs/contributing/components/documentation.md +++ b/docs/docs/contributing/components/documentation.md @@ -35,7 +35,7 @@ Use `pip` to install `mkdocs` and `mkdocs-material`. ## Running the Documentation -Use `mkdocs serve` inside the `docs/` folder to start up a local documentation viewer on port `8000`. +Use `mkdocs serve` inside Tachi's `docs/` folder to start up a local documentation viewer on port `8000`. This will automatically refresh when you edit anything related to the documentation, so you can quickly see how your stuff goes. diff --git a/docs/docs/contributing/setup.md b/docs/docs/contributing/setup.md index 3cb81ae1a..5e5b8f834 100644 --- a/docs/docs/contributing/setup.md +++ b/docs/docs/contributing/setup.md @@ -67,6 +67,10 @@ However, for Windows users we recommend installing the [Windows Terminal](https: Anyway, with a terminal open you can proceed to the next steps! +### Understanding the Terminal + +If you're completely unfamiliar with the terminal, check out our [Terminal Guide](../tools/terminal.md). We'll be assuming you know terminal basics in the below instructions. + ## 1. Getting Node, PNPM and Docker. You'll need `node` to run JavaScript code on your machine. Our codebase is wrote in JS, so this is pretty important. @@ -98,21 +102,39 @@ npm install -g pnpm We use MongoDB and Redis as databases, these external databases require radically different instructions for setup depending on what OS/Linux variant you're on. -As such, we're going to take the lazy route and use something called [Docker](https://docs.docker.com/get-docker/). Get that installed on your PC, and we'll just run the databases inside there. +As such, we're going to take the lazy route and use something called [Docker](https://docker.com). + +```sh +# debian, ubuntu, other derivatives. +# https://docs.docker.com/engine/install/ubuntu/ +# Installing docker on debian & co. is *embarassingly* difficult, to the point where +# the docker team maintain a fairly long, complex script that actually installs it on +# your system. +curl -fsSL https://get.docker.com -o get-docker.sh +sudo sh get-docker.sh + + +# everywhere else it's trivial, of course. +# arch, manjaro, other derivatives. +sudo pacman -S docker docker-compose + +# MacOS +brew install docker docker-compose +``` !!! info Docker is like a VM[^1]. It runs an entire Linux box to contain your software in, and generally sidesteps the whole "works on my machine" problem, by just shipping the entire machine. +!!! question + [Docker Desktop](https://docs.docker.com/desktop/) is something that the Docker team are pushing a bit recently. + + Nobody we know of uses it, but if you want to try it out (it's effectively a docker GUI), let us know how it goes. + ## 2. Fork and pull the repo. -!!! info - You'll need a [GitHub](https://github.com) account. - - They're free - make one if you don't have one! - Since you can't just commit straight to someone elses codebase (that would be a massive security issue), you need to make a fork of Tachi - One owned by you! -Go to [the Tachi repository](https://github.com/TNG-dev/Tachi) and click the Fork button in the top right. +Go to [the Tachi repository](https://github.com/TNG-dev/Tachi) and click the Fork button in the top right (Make sure you're signed in). Now, back to the terminal: @@ -124,7 +146,7 @@ Now, back to the terminal: ```sh # This will create a folder called Tachi on your PC. -# It'll do it wherever your terminal is currently open in. +# It'll create it wherever your terminal is currently open in. git clone https://github.com/YOUR_GITHUB_USERNAME/Tachi # Open this repository in VSCode! diff --git a/docs/docs/contributing/tools/vscode.md b/docs/docs/contributing/tools/vscode.md new file mode 100644 index 000000000..e073df8a2 --- /dev/null +++ b/docs/docs/contributing/tools/vscode.md @@ -0,0 +1,48 @@ +# VSCode Guide + +!!! info + This is an excerpt/early draft from The Long Guide, a guide `zkldi` is writing to + teach people programming from zero. Feedback is very much appreciated. + + As a result, this is also wrote in a far less Tachi-specific tone. + + The Long Guide also makes liberal use of "Detours". These paragraphs provide context + or history for the things that are going on. Reading them will help! + +[VSCode](https://code.visualstudio.com) is an excellent tool for programming. It has everything I've ever wanted, and it's pretty easy to understand. The below content is more like VSCode tips than it is a guide, as the software is fairly approachable. + +## Command Palette + +With `Ctrl-Shift-P`, you can open the command palette. This will let you search *all* possible commands available in VSCode. + +You can search pretty fuzzily, and this means you never really have to memorise keyboard shortcuts (unless you use something a lot, at which point you'll just memorise it anyway!) + +For example, if you type in `Split Editor`, it'll come up with all the commands for splitting your editor in half. In general, if you want to do something in VSCode and don't remember the shortcut, search for it in here! + +## Quick File + +With `Ctrl-P`, you can jump to any file in the folder you have open. + +## Quick Switch + +With `Ctrl-R`, you can switch what project you have open. If you're holding shift, this will open it in a new instance of VSCode. + +## Terminal + +VSCode comes with a built-in terminal. You can open and close it with `Ctrl-J`. + +## Settings + +Everything about VSCode is configurable. Open the settings (You can use `Ctrl-Shift-P` and search for Settings UI!), and twiddle with all the things! + +## Enable Whitespace Viewing + +This is extremely useful in my opinion. Turn on Whitespace Viewing via `View: Toggle Render Whitespace` in the command palette. It's great for finding annoying whitespace bugs in languages where that matters. + +## Extensions + +Finally, VSCode can be extended with extensions. You can grab new themes and colour schemes here (change them by searching for "change theme" in the command palette.) + +You can also add useful extensions, like those that add better support for languages. + +For Tachi contributions, I highly recommend the `ESLint` plugin, as we use `ESLint` to highlight a lot of common errors in our codebase. \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 6635588e1..7064d731a 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -35,6 +35,7 @@ nav: - Tooling Guides: - "contributing/tools/terminal.md" + - "contributing/tools/vscode.md" - Wiki: - "user/overview.md"