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.

Sign up for GitHub

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

Jump to bottom

docs: add syntax highlighting to various code blocks #1391

Merged
merged 1 commit into from
Jan 23, 2025
Merged

docs: add syntax highlighting to various code blocks #1391

merged 1 commit into from
Jan 23, 2025

Conversation

agilgur5
Copy link
Contributor

@agilgur5 agilgur5 commented Jan 21, 2025 •
edited
Loading

Context

Was just reading through the docs here on GH and saw some code blocks were missing syntax highlighting

Details

  • the code blocks were either missing a language specifier entirely, or were using a different flavor of markdown from GH that has different specifiers

    • e.g. lang=python vs python

  • also fix various small markdownlint issues

    • mainly whitespace around codeblocks and headings
    • there's more markdownlint issues, but I only applied some less obtrusive ones

  • and fix a few grammatical errors and formatting errors

    • e.g. missing article ("the"), etc
    • extraneous paren after markdown link, etc

Related issues

Made some other docs improvements in #1392

Has this been tested?

  • [n/a] 👍 yes, I added tests to the test suite
  • [n/a] 💭 no, because this PR is a draft and still needs work
  • 🙅 no, because this is not relevant here
  • [n/a] 🙋 no, because I need help

I manually viewed the rendered markdown and ensured the code now had syntax highlighting. Example

@agilgur5 agilgur5 mentioned this pull request Jan 21, 2025
Merged
1 task
hexaltation
hexaltation approved these changes Jan 21, 2025
View reviewed changes
Copy link
Collaborator

@hexaltation hexaltation left a comment

Choose a reason for hiding this comment

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

Thank you for this cleanup of dev documentation.
LGTM.

paulfitz pushed a commit that referenced this pull request Jan 21, 2025
@agilgur5
docs: add relative links to various file references (#1392)
b12b5d6 
## Context

<!-- Please include a summary of the change, with motivation and context
-->
<!-- Bonus: if you are comfortable writing one, please insert a
user-story https://en.wikipedia.org/wiki/User_story#Common_templates -->

Was just reading through the docs here on GH and saw a lot of references
to files that could have relative links to those files for easy click
through

## Details

<!-- Describe here how you address the issue -->

- when a specific file in the codebase was referenced, link to it
- did not otherwise change the formatting of the content and left it
as-is (e.g. bold text)

- also fix a few incorrect (moved?) locations:
  - `HomeDBManager.ts` now in `homedb/` dir
  - a few files missing extensions
- some incorrect extensions (e.g. was `.ts` but it's actually still
`.js`)
  - having links to the files makes it much easier to find these issues

- and standardize one file reference that was different from the rest
("Python sandbox in this code:" -> "Python sandbox in [...]")

## Related issues

<!-- If suggesting a new feature or change, please discuss it in an
issue first -->
<!-- If fixing a bug, there should be an issue describing it with steps
to reproduce -->
<!-- If this does not solve entirely the issue, make also a checklist of
what is done or not: -->

Made some other docs improvements in #1391

## Has this been tested?

<!-- Put an `x` in the box that applies: -->

- [n/a] 👍 yes, I added tests to the test suite
- [n/a] 💭 no, because this PR is a draft and still needs work
- [x] 🙅 no, because this is not relevant here
- [n/a] 🙋 no, because I need help <!-- Detail how we can help you -->

I double-checked all the links to ensure they worked properly. Also my
code editor (VS Code) would autocomplete the relative paths correctly
when I typed them as another form of check.
paulfitz
paulfitz approved these changes Jan 22, 2025
View reviewed changes
Copy link
Member

@paulfitz paulfitz left a comment

Choose a reason for hiding this comment

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

Thanks @agilgur5 (and @hexaltation for reviewing)

@paulfitz
Copy link
Member

@agilgur5 could you rebase / resolve the conflict?

@agilgur5
docs: add syntax highlighting to various code blocks
815d8f2 
- they were either missing a language specifier entirely, or were using a different flavor of markdown from GH that has different specifiers
  - e.g. `lang=python` vs `python`

- also fix various small `markdownlint` issues
  - mainly whitespace around codeblocks and headings
  - there's more `markdownlint` issues, but I only applied some less obtrusive ones

- and fix a few grammatical errors
  - e.g. missing article ("the"), etc
@agilgur5 agilgur5 force-pushed the docs-syntax-highlighting branch from e70e8ff to 815d8f2 Compare January 22, 2025 21:54
@agilgur5
Copy link
Contributor Author

Rebased and resolved conflicts 👍

@paulfitz paulfitz merged commit 0379b3e into gristlabs:main Jan 23, 2025
10 of 12 checks passed
@agilgur5 agilgur5 deleted the docs-syntax-highlighting branch January 23, 2025 02:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@hexaltation hexaltation hexaltation approved these changes

@paulfitz paulfitz paulfitz approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@agilgur5 @paulfitz @hexaltation