Fix lang declaration on terminal prompts examples

[adammichaelwood]

A bunch of code-block examples for terminal commands are currently labeled rest

(This is my fault, btw.)

They need to be changed.

Currently, the "right" designation is none

But I have recently discovered that sh (for "shell") and console are available.

So I would like for someone to:

• try both console and sh locally (run the build)
• see which, if either, look good
  • if they look the same, choose console
• change all the terminal command examples to the one you pick
• if neither looks good, change all terminal command examples to none

The above does not apply to windows examples. (We'll deal with those in a separate issue.)

While you are at it:

• please make sure all terminal shell examples begin with a $

[mish24]

@opendatakit-bot claim

[mish24]

@adammichaelwood I will work on this. Aren't sh and console similar things though?

[adammichaelwood]

In the syntax highlighter, sh and console are two different lexers.
I think sh is supposed to be for bash scripts (*.sh), and console for terminal sessions.

So console is probably the right thing, but you should check to see which one looks/works better.

Since this is mostly in contributing.rst, you might want to wait for #167 to close before doing this, to avoid having to resolve merge conflicts.

[NjeriNjoroge]

Hi, i would like to work on this. Please tell me how I can get started?

[lognaturel]

Hi @NjeriNjoroge, it looks like @mish24 is already on this one! You can see that she claimed it a few comments up.

I would recommend that you start by reading through the existing documentation and making sure you understand it. It's likely you'll find a small typo or spelling error and then you can file a line edit pull request as described at #96

[mish24]

Hello, something interesting came up. Apparently sh and console aren't same. One produces different colored output for shell commands, whereas other just turns everything inside the block to gray. none is just all black and white, whereas rest is able to differentiate between code example and the text. Like in the examples given for sphinx documentation, it turns the actual syntax into gray, and text which follows it into black. So it looks good to use rest there. @adammichaelwood Is this okay?

[mish24]

One important thing - code-block is rendered on terminal and not online.

[adammichaelwood]

can you provide screen shots for discussion?

[adammichaelwood]

code-block is rendered on terminal and not online.

I don't know what you mean here

[mish24]

In the example here, the restructured text example syntax as well as the line that follows are black.

[mish24]

We want the code of .rst format to be in gray, and the text in black. http://build-me-the-docs-please.readthedocs.io/en/latest/Using_Sphinx/ShowingCodeExamplesInSphinx.html#pygments-lexers --> all these types of code-blocks can be used, which will just gray up the content which is written in that programming language, and everything else remains black.

[adammichaelwood]

We are only discussing the code samples related to terminal commands

The code samples showing restructured text will stay rest for the lang declaration

[adammichaelwood]

The question was whether console or sh will make the terminal commands look better.

[mish24]

Here the source odkenv/bin/activate uses console. sh just turns everything gray.

[mish24]

So we want the terminal commands in gray or black? If it's gray it'll be sh.

[mish24]

In my opinion, black looks much better than gray.

[mish24]

Also, rest has to be changed to rst everywhere.

[adammichaelwood]

I think we should use console for console sessions. It is "correct" and seems to do some appropriate syntax highlighting.

rest has to be changed to rst everywhere.

It doesn't, actually. They are the same thing.
But it might make it more clear.

If you want to change rest to rst, you can. It doesn't really matter.
Just don't do a find-and-replace, or you'll end up changing things you don't mean to.

[mish24]

@adammichaelwood Okay! I'll change it to console then!

[adammichaelwood]

Just a note of clarification:

restructured text samples need to be rest (or rst)

bash console (terminal commands) should be console
(most of them are currently rest or none -- because I made a mistake and labeled them rest)

actual bash shell script examples should be sh (I can only think of one)

.gitignore and .gitattributes should be none

[adammichaelwood]

it might be helpful to make a note in the docs where it mentions using .code-block

[mish24]

@adammichaelwood Where is the sh one? I'm sorry I couldn't point it out. Yes, I will add notes too.

[adammichaelwood]

On Mac, add the following to your .bash_profile
export PATH=$PATH:~/Library/Android/sdk/tools/

[adammichaelwood]

closed via #176