Skip to content
This repository has been archived by the owner on May 10, 2023. It is now read-only.

Fix tutorial typos and improve styling #111

Closed

Conversation

alejandromumo
Copy link
Member

Fixed typos in tutorial's README.

Improved styling following markdown linting rules using markdownlint, as suggested in #83 . Namely:

  • Fixed indentation for code blocks and text inside a list's item. Apart from being unsightly in the rendered markdown, also triggered linting's rule md029.
  • Fixed commandline vs bash vs console inconsistencies in code-blocks containing shell commands. For instance:
    • Replaced commandline with console whenever the written command contains prompts. E.g:
      john@doe:~$ ls -la
      foo bar
      Instead, if using bash it would render as:
      john@doe:~$ ls -la
      foo bar
      Otherwise, bash can be used.
    • bash with or without $. Added $ before a command with output, removed it otherwise following linting rule md014.
  • Fixed trailing spaces md009 and EOF spaces md047
  • Fixed blank lines surrounding headers, following rule md022

@avivace avivace self-requested a review February 11, 2022 09:26
Copy link
Member

@avivace avivace left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @alejandromumo ! I left some comments, but it looks good so far. Can you rebase the branch so it has only one / meaningful commits?

@@ -155,7 +155,7 @@ If we want to be more precise and change a concrete CSS rule we can add it direc
After changing the file, we have to rebuild our assets using the `invenio
webpack` command:

```bash
```console
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here are you replacing the bash syntax highlighting with console but in other occurences the other way round? (e.g. in 13-securing-your-instance/README.md?)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

console can be used when a command has prompt. In this case, (my-site) $ invenio webpack buildall contains a prompt. That way, prompt is properly styled when rendered.
bash can be used otherwise, as in https://github.com/inveniosoftware/training/pull/111/files#diff-40659415052de7162a64a8e03acc79f60e6592424c71a8826849917684e1380f where command does not contain any prompt.

@@ -114,7 +114,7 @@ Run tests again:

In order to test a new package, simply install it in the virtualenv using `pip` tool:

```bash
```console
(my-site)$ pip install Pillow
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we decide to remove every $ character to make the strings copy-pastable maybe we should to the same with the virtual env prompts (if no additional clarificaiton on it being used is required)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have any objection to that.
But these prompts provide a hint to the reader that the command was run in a specific venv. Otherwise the command should be modified as well (e.g. in this case pipenv run pip install Pillow)

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants