Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: cleanup code blocks in bullets #152

Merged

Conversation

Billy99
Copy link
Contributor

@Billy99 Billy99 commented May 1, 2024

New to Kepler and was trying to follow the documentation to install Kepler for the first time. The
https://sustainable-computing.io/installation/kepler/#deploy-the-prometheus-operator section has several issues. Primarily, some of the code blocks lead with console in the text, new lines are not honored, and the bulleted numbers don't increment.

Fixes in this PR:

  • Added pymdownx.superfences to the markdown_extensions: section in mkdocs.yml. This fixed the newlines not honored in the indented code blocks and allowed the build to recognize the code block language identifier (console).
  • Added additional spaces to the code blocks in bulleted sections. This indents the code block to the same level as the text and allows the bulleted numbers to increment properly.
  • For code blocks, replaced # with a $. To me, # implies root access is required and none of the documented commands require root access. I will change this globally in the docs if this change is acceptable.
  • Added admonition to the markdown_extensions: section in mkdocs.yml. When adding things like Note:, with admonition, if !!! note is used instead, it draws a box around the note. See https://squidfunk.github.io/mkdocs-material/reference/admonitions/. I can remove this, or update the docs globally depending on feedback.
  • Changed the default language to English. When building and running locally, it defaulted to Chinese. The problem is that only 3 of the pages are translated into Chinese so it looked like it was in English except for those 3 pages on the table of content. So took a while to figure out that the language for the whole website was set to Chinese and that there wasn't some other issue.

@Billy99 Billy99 force-pushed the billy99-bullet-code-block branch from 1da30b9 to 099edf4 Compare May 2, 2024 01:56
New to Kepler and was trying to follow the documentation to install
Kepler for the first time. The
https://sustainable-computing.io/installation/kepler/#deploy-the-prometheus-operator
section has several issues. Primarily, some of the code blocks lead with
`console` in the text, new lines are not honored, and the bulleted
numbers don't increment.

Fixes in this PR:
* Added `pymdownx.superfences` to the `markdown_extensions:` section in
  `mkdocs.yml`. This fixed the newlines not honored in the indented code
  blocks and allowed the build to recognize the code block language
  identifier (`console`).
* Added additional spaces to the code blocks in bulleted sections. This
  indents the code block to the same level as the text and allows the
  bulleted numbers to increment properly.
* For code blocks, replaced `#` with a `$`. To me, `#` implies root
  access is required and and none of the documented commands require
  root access. I will change this globally in the docs if this change is
  acceptable. `$` causes a lint error so I removed them.
  `MD014/commands-show-output Dollar signs used before commands without
  showing output`
* Added `admonition` to the `markdown_extensions:` section in
  mkdocs.yml. When adding things like `Note:`, with `admonition`, is
  `!!! note` is used, it draws a box around the note. See
  https://squidfunk.github.io/mkdocs-material/reference/admonitions/.
  I can remove this, or update the docs globally depending on feedback.
* Changed the default language to English. When building and running
  locally, it defaulted to Chinese. The problem is that only 3 of the
  pages are translated into Chinese so it looked like it was in English
  except for those 3 pages on the table of content. So took a while to
  figure out that the language for the whole website was set to Chinese
  and that there wasn't some other issue.

Signed-off-by: Billy McFall <22157057+Billy99@users.noreply.github.com>
@Billy99
Copy link
Contributor Author

Billy99 commented May 2, 2024

$ causes a lint error so I removed them.
MD014/commands-show-output Dollar signs used before commands without showing output
See: https://github.com/updownpress/markdown-lint/blob/master/rules/014-commands-show-output.md

This can be squashed once reviewed.

Additional changes:
* Globally updated `>Notes: to `!!! notes` as done in original commit.
* Globally removed `# ` that were in code blocks that didn't require
  root access.
* Globally indented code blocks in bullet items so the code block
  matched up with the bullet text.
* Changed all `kepler` to `Kepler` were applicable.
* Fixed typos or bad grammer as they were stumbled upon.

Signed-off-by: Billy McFall <22157057+Billy99@users.noreply.github.com>
@Billy99 Billy99 force-pushed the billy99-bullet-code-block branch from 099edf4 to 298f1a4 Compare May 2, 2024 17:05
@Billy99
Copy link
Contributor Author

Billy99 commented May 2, 2024

Since @rootfs approved the original commit, made the following additional changes globally:

  • Globally updated >Notes: to !!! notes as done in original commit.
  • Globally removed # that were in code blocks that didn't require root access.
  • Globally indented code blocks in bullet items so the code block matched up with the bullet text.
  • Changed all kepler to Kepler were applicable.
  • Fixed typos or bad grammer as they were stumbled upon.
  • In docs/design/kepler-energy-sources.md, rearranged some of the text to help it read better. Same text, just different order.
  • In lines I was already changing for other reasons, it the line was too long, broke it up over several lines.
  • Headings should be capitalized. I didn't change every instance, but in some of the places I was already making changes, I updated some of the heading capitalization.
  • In docs/design/metrics.md, I fixed the spacing around each counter. Now the text is on a separate line from the counter name.

@rootfs rootfs merged commit 24f4b03 into sustainable-computing-io:main May 2, 2024
2 checks passed
@Billy99 Billy99 deleted the billy99-bullet-code-block branch May 2, 2024 17:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants