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] Rationalise admonitions in documentation #564

Merged
merged 17 commits into from
Jul 9, 2024

Conversation

stichbury
Copy link
Contributor

@stichbury stichbury commented Jul 3, 2024

Description

Rationalisation of the admonitions used across core and vizro-ai docs.

  • Removed or replaced any tip and info 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 time
    • example 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)
  • Removed any expanded-on-load collapsibles (or replaced with standard expanded versions). On the whole, I think we should avoid collapsibles unless there are lengthy chunks of code that not everyone needs to read, or there's a side note that doesn't really apply to everyone (like the one on "Do you want to work exclusively in the browser and never touch the console?" kind of thing.
  • Removed/replaced some admonitions where they were unnecessary
  • Updated the documentation style guide to reflect the thinking behind this rationalisation

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":

    • I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
    • I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
    • I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
    • I have not referenced individuals, products or companies in any commits, directly or indirectly.
    • I have not added data or restricted code in any commits, directly or indirectly.

@stichbury stichbury temporarily deployed to circleci_secrets July 3, 2024 16:11 — with GitHub Actions Inactive
@stichbury stichbury changed the title [Docs] Rationalise admonitions [Docs] Rationalise admonitions in documentation Jul 3, 2024
@stichbury stichbury added Status: Ready for Review ☑️ Docs 🗒️ Issue for markdown and API documentation labels Jul 3, 2024
@stichbury stichbury self-assigned this Jul 3, 2024
Copy link
Contributor

@huong-li-nguyen huong-li-nguyen left a 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

vizro-ai/docs/pages/user-guides/install.md Show resolved Hide resolved
vizro-core/docs/pages/user-guides/assets.md Outdated Show resolved Hide resolved
vizro-core/docs/pages/user-guides/custom-charts.md Outdated Show resolved Hide resolved
vizro-core/docs/pages/user-guides/install.md Show resolved Hide resolved
@stichbury stichbury temporarily deployed to circleci_secrets July 8, 2024 13:43 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 8, 2024 13:43 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 8, 2024 13:43 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 8, 2024 13:43 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 8, 2024 13:44 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 8, 2024 13:44 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to circleci_secrets July 9, 2024 11:25 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:25 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:25 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:25 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:25 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:25 — with GitHub Actions Inactive
@pre-commit-ci pre-commit-ci bot temporarily deployed to circleci_secrets July 9, 2024 11:26 Inactive
@pre-commit-ci pre-commit-ci bot temporarily deployed to vizro_ai_secrets July 9, 2024 11:26 Inactive
@pre-commit-ci pre-commit-ci bot temporarily deployed to vizro_ai_secrets July 9, 2024 11:26 Inactive
@pre-commit-ci pre-commit-ci bot temporarily deployed to vizro_ai_secrets July 9, 2024 11:26 Inactive
@pre-commit-ci pre-commit-ci bot temporarily deployed to vizro_ai_secrets July 9, 2024 11:26 Inactive
@pre-commit-ci pre-commit-ci bot temporarily deployed to vizro_ai_secrets July 9, 2024 11:26 Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:37 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to circleci_secrets July 9, 2024 11:37 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:37 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:37 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:37 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:37 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to circleci_secrets July 9, 2024 11:38 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:38 — with GitHub Actions Inactive
@stichbury stichbury enabled auto-merge (squash) July 9, 2024 11:38
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:38 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:38 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:38 — with GitHub Actions Inactive
@stichbury stichbury temporarily deployed to vizro_ai_secrets July 9, 2024 11:38 — with GitHub Actions Inactive
@stichbury stichbury merged commit 37d7ac6 into main Jul 9, 2024
37 checks passed
@stichbury stichbury deleted the docs/admonition-review branch July 9, 2024 11:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Docs 🗒️ Issue for markdown and API documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants