-
Notifications
You must be signed in to change notification settings - Fork 144
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] Rationalise admonitions in documentation #564
Merged
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
stichbury
temporarily deployed
to
circleci_secrets
July 3, 2024 16:11 — with
GitHub Actions
Inactive
stichbury
changed the title
[Docs] Rationalise admonitions
[Docs] Rationalise admonitions in documentation
Jul 3, 2024
stichbury
added
Status: Ready for Review ☑️
Docs 🗒️
Issue for markdown and API documentation
labels
Jul 3, 2024
stichbury
requested review from
Joseph-Perkins,
Anna-Xiong,
lingyielia,
maxschulz-COL,
antonymilne and
huong-li-nguyen
as code owners
July 3, 2024 16:15
stichbury
temporarily deployed
to
vizro_ai_secrets
July 3, 2024 16:15 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
circleci_secrets
July 3, 2024 16:15 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 3, 2024 16:15 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 3, 2024 16:15 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 3, 2024 16:15 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 3, 2024 16:15 — with
GitHub Actions
Inactive
huong-li-nguyen
approved these changes
Jul 8, 2024
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM 👍 Have some minor comments and questions
Co-authored-by: Li Nguyen <[email protected]>
stichbury
temporarily deployed
to
circleci_secrets
July 8, 2024 13:43 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 8, 2024 13:43 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 8, 2024 13:43 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 8, 2024 13:43 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 8, 2024 13:44 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 8, 2024 13:44 — with
GitHub Actions
Inactive
Co-authored-by: Li Nguyen <[email protected]>
stichbury
temporarily deployed
to
circleci_secrets
July 9, 2024 11:25 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:25 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:25 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:25 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:25 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:25 — with
GitHub Actions
Inactive
for more information, see https://pre-commit.ci
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:37 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
circleci_secrets
July 9, 2024 11:37 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:37 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:37 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:37 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:37 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
circleci_secrets
July 9, 2024 11:38 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:38 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:38 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:38 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:38 — with
GitHub Actions
Inactive
stichbury
temporarily deployed
to
vizro_ai_secrets
July 9, 2024 11:38 — with
GitHub Actions
Inactive
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Rationalisation of the admonitions used across core and vizro-ai docs.
tip
andinfo
admonitions so we have just 4 types:warning
for explicit admonitions. Use these where the reader could make an error that causes them to waste timeexample
the purple testube!note
for asides that are things we want to call out or slight "asides" that fit better in a box (sometimes collapsed)details
(used sparingly in the explanation page to hide lengthy text chunks that are more marketing than docs)There are probably still too many admonitions on some pages (e.g. the get started content in
vizro-core
) but they do break up the text so I've retained them for now.Next step (different PR in the future) would be to customise these to use a colour palette supplied by design.
One thing to note is that vale doesn't currently run on admonitions (to avoid it checking code and failing) so whenever we convert an admonition to normal text, it gets checked and can then show up issues.
Ideally we should revise the vale configuration so it does check admonitions except for "example" but this is probably beyond my level of skill with the tool.
Screenshot
Notice
I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":