Add "custom setups" section #24

gwenzek · 2020-07-20T09:24:03Z

The idea is to collect a bunch of resources How to use Sublime for doing X.
Sublime generally need some setup when you start working seriously with one language/programming stack.
Having those guides will help new ST users to get started with a new project.

This PR adds:

How to use Sublime for remote devlopment which I authored.
How to use Sublime with Julia from @PetrKryslUCSD.

Let's discuss what's would be the best place to put those guides :-)

I cleaned up Julia guide to focus on Julia exclusively. I'm not sure about some the Zeal configuration files it seems to be outdated.
Pages mentionning plugins may tend to be obsolete faster than the rest of the documentation because the plugins API tend to evolve faster than core ST.
So maybe those pages should have a proeminent timestamp or versions of the mentioned plugins.

What are you thoughts on this ?

EDIT: maybe there should be some guidelines for authors of those guides. Things I tried to apply to myself:

Make the guide incremental:
Don't start by asking the user to install 5 plugins and then explain how they are used. Start minimalist and add features/plugins progressively.
Explicit your workflow from the start, so that people can see if they something they want to use.
Explicit the OS used, ST is cross-platform, but some plugins need extra configuration for specific OS.
Encourage the use of command palette instead of menus.

It would also be helpful if we could assume the readers know about Package Contrrol, Command Palette, ...

gwenzek · 2020-07-20T09:36:42Z

Also I just read Contributing.md so there is a few formatting that I need to do, but I'm happy to have the rest of the discussion already.

EDIT: formatting ok :-)

PetrKryslUCSD · 2020-07-20T14:37:56Z

This looks good. I agree that the number of plugins discussed can be reduced.

gwenzek · 2020-07-21T08:10:17Z

@PetrKryslUCSD I think the plugins you listed are good, but maybe they should be listed elsewhere.
Otherwise people not interested in Julia won't see them.
I tried to focus on just your Julia workflow with the REPL integration.

EDIT: I previoulsy said Lua where I meant Julia. (Damn, so many programming languages to learn !)

PetrKryslUCSD · 2020-07-21T15:53:46Z

Did you mean Julia? And I'm not sure what it is you're suggesting. Would you care to elaborate? Petr Krysl Prof. and Vice chair for undergraduate education Structural engineering department University of California, San Diego

…

On Tue, Jul 21, 2020 at 1:10 AM gwenzek ***@***.***> wrote: @PetrKryslUCSD <https://mailtrack.io/trace/link/cf2668fb9869228aa507b3570a4e9ce8f80674b1?url=https%3A%2F%2Furldefense.com%2Fv3%2F__https%3A%2F%2Fgithub.com%2FPetrKryslUCSD__%3B!!Mih3wA!VIShL4V1RXq3PkHsUZx5uBhs8JuTGRTCjMj0mhNXbFi_rdneC5i07zhvBzsTRtU%24&userId=1197778&signature=1d10b62bfeaf12fb> I think the plugins you listed are good, but maybe they should be listed elsewhere. Otherwise people not interested in Lua won't see them. I tried to focus on just your Lua workflow with the REPL integration. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <https://mailtrack.io/trace/link/277fcfe1398fdbe5850eb96697e373c3c7d3a5f9?url=https%3A%2F%2Furldefense.com%2Fv3%2F__https%3A%2F%2Fgithub.com%2Fsublimetext-io%2Fdocs.sublimetext.io%2Fpull%2F24*issuecomment-661705598__%3BIw!!Mih3wA!VIShL4V1RXq3PkHsUZx5uBhs8JuTGRTCjMj0mhNXbFi_rdneC5i07zhv67MmO3c%24&userId=1197778&signature=db5aaf278b808268>, or unsubscribe <https://mailtrack.io/trace/link/a9ba4c325292abf0af0e1438c685e5f49e3eaceb?url=https%3A%2F%2Furldefense.com%2Fv3%2F__https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FACLGGWGXILZ5LJP4A7CF433R4VEPTANCNFSM4PCCUIBQ__%3B!!Mih3wA!VIShL4V1RXq3PkHsUZx5uBhs8JuTGRTCjMj0mhNXbFi_rdneC5i07zhvJmn2Ke8%24&userId=1197778&signature=1815164cb58a2a6f> .

FichteFoll · 2020-07-22T00:15:52Z

So maybe those pages should have a proeminent timestamp or versions of the mentioned plugins.

According to the vue docs, the "Last Updated" texts at the end of every page should contain a timestamp of when that page was last updated, but in my quick tests on the live site, all of them had the same timestamp, despite the input handlers page being the last one to receive updates. Seems like it's not working properly.

maybe there should be some guidelines for authors of those guides

Definitely, but let's see what works first. Thanks for writing down your thoughts already, though, as that will surely be a good starting point.

It would also be helpful if we could assume the readers know about Package Contrrol, Command Palette, ...

The command palette should be known at this point in the guide as it is explained in the Basics section. You can reference the page where it is explained, if you want to, but only once preferrably. Package Control is only mentioned in the installing packages section, which is not prominent enough in my taste, but I have a local todo item to improve that at least. You shouldn't have to deal with it in a page describing a certain environment.

FichteFoll · 2020-07-22T00:17:44Z

docs/guide/setup-examples/README.md

@@ -0,0 +1,16 @@
+---
+title: Introduction


This should read "Example Setups" and the folder name should reflect the name of this section.

docs/guide/setup-examples/julia.md

FichteFoll · 2020-07-22T00:20:08Z

docs/guide/setup-examples/julia.md

+I like having my source code on the left
+and a terminal running Julia REPL on the right.
+This setup will allow you to have the terminal inside Sublime
+and to have commands that send code under your cursor to the REPL.


A screenshot showing this would be nice.

docs/guide/setup-examples/julia.md

FichteFoll · 2020-07-22T00:34:21Z

docs/guide/setup-examples/julia.md

+
+## Credits
+
+Thanks to Petr Krysl, Paul Soderlind, @mbauman.


@mbauman doesn't really help without a namespace or a URL. Is this a handle on Twitter, Github or some other random site?

docs/guide/setup-examples/remote_dev.md

FichteFoll · 2020-07-22T00:37:33Z

docs/guide/setup-examples/remote_dev.md

+ AddKeysToAgent yes
+ UseKeychain yes
+ ControlPath ~/.ssh/ssh-%r@%h:%p
+ ControlMaster auto
+ ServerAliveInterval 240
+ Port 22


All these options are optional and unless they are required, users shouldn't be asked to copy random congifuration options into their setup that they don't need or understand. That's my ideal, at least.

AddKeysToAgent is debatable and more useful than the others (and especially the default), so that can probably remain.

In my case I need the ControlPath, ControlMaster because I have 2-factor authentication.
I split the instructions in two, and added more details

FichteFoll

Thanks for moving these pages over to the Community Docs project. This is definitely going in the right direction. I just left a couple comments on things I'd like to discuss or that should be changed.

docs/guide/setup-examples/remote_dev.md

FichteFoll · 2020-07-22T00:39:31Z

docs/guide/setup-examples/remote_dev.md

+SFTP is a Sublime Text package that will allow you to keep in sync files
+on your laptop and on a server.
+
+Install https://packagecontrol.io/packages/SFTP


Missing period. Should probably also be an ordered list.

not sure what you meant. I made the installation instructions a list.

That's almost what I meant (unordered instead of ordered), but workable for now.

docs/guide/setup-examples/remote_dev.md

FichteFoll · 2020-07-22T00:48:11Z

docs/guide/setup-examples/remote_dev.md

+Note that it still takes a few seconds to run
+so if you start a job on your server just after pulling,
+you may end up running code from the old branch.
+


As another alternative, inotifywait could be used to schedule an rsync run when files are changed. I have the following script in my path

#!/bin/sh FORMAT=$(echo -e "\n\033[1;33m ==> %w%f written\033[0m") "$@" while inotifywait -qre close_write --format "$FORMAT" . do "$@" done

so do you need to run this command every time you start working on your project ?
it doesn't seems fool-proof.

That is correct, but I find it reasonable to explicitly start a monitoring sync process like rsync. Anyway, that was just an additional idea.

FichteFoll · 2020-07-22T00:55:14Z

Oh, you also need to add the pages to .vuepress/config.js so they will be added to the sidebar. I can also do that if you don't want to deal with reading vuepress documentation.

gwenzek · 2020-08-03T21:39:07Z

Thanks for the review, I improved the "remote development" guide further.

I'm not sure what to do next for the Julia one. There are some parts that I believe could be simplified,
but given I'm neither a Windows user nor aJulia user, I'm not sure I'm the best person to do that.
In particular I'm not sure you need to create a fake ST executable to have Julia opening in the Git Bash rather than in the Windows shell (CMD).

The idea was to show what a language specific guide could look like, but maybe it should be move to separate PR to clean it more.

FichteFoll

Good changes here. Please address the remaining comments (and the few I added here) and we can go ahead and merge.

FichteFoll · 2020-08-14T14:02:51Z

docs/guide/setup-examples/julia.md

+In the file `USER\Terminus.sublime-settings`,
+chose your favorite shell.
+
+customize the Linux shell of the Windows Subsystem for Linux,


Incomplete sentence.

FichteFoll · 2020-08-14T14:08:03Z

docs/guide/setup-examples/remote_dev.md

+to upload the whole folder to your server.
+
+To keep the remote code always a mirror of the code on your laptop,
+you want to automatically run `rsync_git` when you checkout a branch:

 ```sh
 echo "source ~/.zshrc; rsync_git" > .git/post-checkout


It should be noted that hooks executed according to their shebang line and I'm not sure if they use $SHELL as the default if none exists. Since you're sourcing your zshrc, you'd probably want it to be interpreted by zsh.

FichteFoll · 2020-08-14T14:08:57Z

docs/guide/setup-examples/remote_dev.md

+Note that it still takes a few seconds to run
+so if you start a job on your server just after pulling,
+you may end up running code from the old branch.
+


That is correct, but I find it reasonable to explicitly start a monitoring sync process like rsync. Anyway, that was just an additional idea.

FichteFoll · 2020-08-14T14:11:15Z

docs/.vuepress/config.js

+ title: 'Example Setups',
+ path: '/guide/setup-examples/',


These names are still out of sync.

bkoski · 2021-06-27T20:19:03Z

@gwenzek - introduced #54 that ideally would build on this "Example Setups" framework, if it's possible to tidy up and merge this PR!

gwenzek added 3 commits July 20, 2020 10:59

add remote dev setup guide

2da87ff

add Julia dev setup guide.

ed6ff89

add link to setups page in guide entry point.

6afb4a4

gwenzek added 2 commits July 20, 2020 12:08

format julia.md

c53bde0

format remote_dev.md

a26815a

FichteFoll reviewed Jul 22, 2020

View reviewed changes

FichteFoll requested changes Jul 22, 2020

View reviewed changes

gwenzek added 3 commits August 3, 2020 23:25

rewrite from 1st person to 3rd person

321846d

add to config.js

93b4228

minor improvements from FichteFoll

29cb733

gwenzek requested a review from FichteFoll August 3, 2020 21:34

FichteFoll requested changes Aug 14, 2020

View reviewed changes

bkoski mentioned this pull request Jun 27, 2021

Add Example Setup for TypeScript #54

Open

bkoski mentioned this pull request Jun 27, 2021

Suggestion: community wiki or cookbooks for getting started on common development envs sublimehq/sublime_text#4495

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add "custom setups" section #24

Add "custom setups" section #24

gwenzek commented Jul 20, 2020 •

edited

gwenzek commented Jul 20, 2020 •

edited

PetrKryslUCSD commented Jul 20, 2020

gwenzek commented Jul 21, 2020 •

edited

PetrKryslUCSD commented Jul 21, 2020 via email

FichteFoll commented Jul 22, 2020

FichteFoll Jul 22, 2020

FichteFoll Jul 22, 2020

FichteFoll Jul 22, 2020

FichteFoll Jul 22, 2020 •

edited

gwenzek Aug 3, 2020

FichteFoll left a comment

FichteFoll Jul 22, 2020

gwenzek Aug 3, 2020

FichteFoll Aug 14, 2020

FichteFoll Jul 22, 2020

gwenzek Aug 3, 2020

FichteFoll Aug 14, 2020

FichteFoll commented Jul 22, 2020

gwenzek commented Aug 3, 2020

FichteFoll left a comment

FichteFoll Aug 14, 2020

FichteFoll Aug 14, 2020

FichteFoll Aug 14, 2020

FichteFoll Aug 14, 2020

bkoski commented Jun 27, 2021

Add "custom setups" section #24

Are you sure you want to change the base?

Add "custom setups" section #24

Conversation

gwenzek commented Jul 20, 2020 • edited

gwenzek commented Jul 20, 2020 • edited

PetrKryslUCSD commented Jul 20, 2020

gwenzek commented Jul 21, 2020 • edited

PetrKryslUCSD commented Jul 21, 2020 via email

FichteFoll commented Jul 22, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

FichteFoll Jul 22, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

FichteFoll left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

FichteFoll commented Jul 22, 2020

gwenzek commented Aug 3, 2020

FichteFoll left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bkoski commented Jun 27, 2021

gwenzek commented Jul 20, 2020 •

edited

gwenzek commented Jul 20, 2020 •

edited

gwenzek commented Jul 21, 2020 •

edited

FichteFoll Jul 22, 2020 •

edited