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

Improvements to documentation #12712

Merged
merged 5 commits into from
Aug 12, 2024
Merged

Conversation

eth3lbert
Copy link
Contributor

Summary

As we did in astral-sh/uv#5397, we improve the copy behavior for documentation in this PR.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I had an issue before updating the dependencies. Now these dependencies should be the same as in uv.

Copy link
Member

Choose a reason for hiding this comment

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

Are there any changes which requires the dependency upgrade? If not, I'd prefer to keep the upgrades separate as they could require some changes in the config / docs.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This PR primarily introduce extra js for the copy button.

Without upgrading dependencies, if you try to start the server, you will encounter a jinja2.exceptions.UndefinedError: 'mkdocs.config.config_options.ExtraScriptValue object' has no attribute 'endswith' error.

This issue has been fixed in a newer version, as seen in the release notes: https://www.mkdocs.org/about/release-notes/#version-152-2023-08-02. Therefore, I believe it's best to also upgrade the dependencies to match the version used by uv.

Copy link
Member

Choose a reason for hiding this comment

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

Interesting. It seems that uv's insider version is also fixed to mkdocs==1.5.0.

Copy link
Member

Choose a reason for hiding this comment

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

Copy link
Member

@MichaReiser MichaReiser Aug 9, 2024

Choose a reason for hiding this comment

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

Copy link
Member

Choose a reason for hiding this comment

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

What I understand is that this issue was fixed in 1.5.2. I would prefer if we upgraded to the latest 1.5.x version instead of bumping the minor as part of this PR.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Fair enough!

Copy link
Member

Choose a reason for hiding this comment

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

And I hope that it solves all regressions so that we can merge this PR :)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Since I don't have access to the insider version, I can't help much if regressions occur.

@eth3lbert
Copy link
Contributor Author

\cc @zanieb

@eth3lbert
Copy link
Contributor Author

(I don't have access to mkdocs insider, so I don't change insider-related dependencies.)

Copy link
Contributor

github-actions bot commented Aug 6, 2024

ruff-ecosystem results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.

Formatter (stable)

ℹ️ ecosystem check encountered format errors. (no format changes; 1 project error)

openai/openai-cookbook (error)

warning: Detected debug build without --no-cache.
error: Failed to parse examples/Chat_finetuning_data_prep.ipynb:6:18:25: Unparenthesized generator expression cannot be used here
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_box.ipynb:13:1:1: Expected an expression
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_confluence.ipynb:15:1:5: Simple statements must be separated by newlines or semicolons
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_gmail.ipynb:15:1:1: Expected an expression
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_jira.ipynb:15:1:1: Expected an expression
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_notion.ipynb:15:1:1: Expected an expression
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_sharepoint_doc.ipynb:28:1:5: Simple statements must be separated by newlines or semicolons
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_sharepoint_text.ipynb:28:1:5: Simple statements must be separated by newlines or semicolons
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_sql_database.ipynb:2:2:5: Simple statements must be separated by newlines or semicolons
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_middleware_azure_function.ipynb:37:1:13: Simple statements must be separated by newlines or semicolons

Formatter (preview)

ℹ️ ecosystem check encountered format errors. (no format changes; 1 project error)

openai/openai-cookbook (error)

ruff format --preview

warning: Detected debug build without --no-cache.
error: Failed to parse examples/Chat_finetuning_data_prep.ipynb:6:18:25: Unparenthesized generator expression cannot be used here
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_box.ipynb:13:1:1: Expected an expression
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_confluence.ipynb:15:1:5: Simple statements must be separated by newlines or semicolons
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_gmail.ipynb:15:1:1: Expected an expression
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_jira.ipynb:15:1:1: Expected an expression
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_notion.ipynb:15:1:1: Expected an expression
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_sharepoint_doc.ipynb:28:1:5: Simple statements must be separated by newlines or semicolons
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_sharepoint_text.ipynb:28:1:5: Simple statements must be separated by newlines or semicolons
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_sql_database.ipynb:2:2:5: Simple statements must be separated by newlines or semicolons
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_middleware_azure_function.ipynb:37:1:13: Simple statements must be separated by newlines or semicolons

Copy link
Member

@MichaReiser MichaReiser left a comment

Choose a reason for hiding this comment

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

Nice!

I think the updated dependencies are creating trouble in our documentation generation script (see CI).

Is it intentional that this PR updates markdown files that aren't hosted on the website?

README.md Outdated
```shell
# With pip.
pip install ruff
```console
Copy link
Member

Choose a reason for hiding this comment

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

Does this change how github or pypi renders the readme?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Good point! This does change how it appears on github (and maybe pypi too), but readme on those platforms wouldn't benefit from the patch we introduced in this PR. So, the dollar sign will still be displayed, and we can't just ignore it when copying.

Therefore, we probably shouldn't include this change in the README.md, right?

Copy link
Member

Choose a reason for hiding this comment

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

Yeah. I think we should only change the markdown files in the docs folder.

Copy link
Contributor Author

@eth3lbert eth3lbert Aug 7, 2024

Choose a reason for hiding this comment

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

Hmm, actually it seems we only want to apply the changes to files in the crates/ or docs/ directories?

Yeah, we should just change files that are hosted on site.

docs/js/extra.js Show resolved Hide resolved
@MichaReiser MichaReiser added the documentation Improvements or additions to documentation label Aug 7, 2024
@MichaReiser
Copy link
Member

I can look into the mkdocs failure once we answered all other questions.

@MichaReiser
Copy link
Member

I upgraded the insider version but it breaks some styling. For example, the tab headers no longer use the correct colors

image

@MichaReiser
Copy link
Member

For some reason, I'm unable to scroll to the end of the navigation on localhost but it works fine in production. I yet have to verify if this is due to the upgrade

image

@MichaReiser
Copy link
Member

MichaReiser commented Aug 7, 2024

I clicked through the page and most things look okay after the upgrade but there are some regression that needs fixing before we can ship this. I would also like @charliermarsh or @zanieb to have a look at this. They'll know better why the insider version on uv is out of sync

This is the requirements-insiders.txt that i used

PyYAML==6.0.1
black==23.10.0
mkdocs==1.6.0
mkdocs-material @ git+ssh://[email protected]/astral-sh/mkdocs-material-insiders.git@2fcb87fe9f685cae13e7161daf459177d2da08c0
mkdocs-redirects==1.2.1
mdformat==0.7.17
mdformat-mkdocs==3.0.0
mdformat-admon==2.0.6

@eth3lbert
Copy link
Contributor Author

eth3lbert commented Aug 7, 2024

I upgraded the insider version but it breaks some styling. For example, the tab headers no longer use the correct colors

image

Yeah, I could also see this happening locally without using the insider version.
It seems like it used to use color: var(--md-accent-fg-color); but now uses color: var(--md-default-fg-color); afterwards.

And this likely didn't happen with mkdocs-material==9.1.18.

docs/js/extra.js Outdated
Comment on lines 29 to 28
const start = performance.now();

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Should this be removed before merging, or is it intentional?

Copy link
Member

Choose a reason for hiding this comment

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

Oops no. I'm sorry. That's absolutely not intentional

docs/js/extra.js Outdated
@@ -37,6 +39,8 @@ function setCopyText() {
);
}
});

console.log(performance.now() - start);
Copy link
Contributor Author

Choose a reason for hiding this comment

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

ditto.

@MichaReiser
Copy link
Member

The trick is to not upgrade mkdocs-material

@MichaReiser MichaReiser enabled auto-merge (squash) August 12, 2024 07:13
@MichaReiser MichaReiser merged commit 59f712a into astral-sh:main Aug 12, 2024
16 checks passed
@eth3lbert
Copy link
Contributor Author

Indeed! I also found it #12712 (comment).

I love the improvement you've introduced in the latest commit. 👍

@eth3lbert eth3lbert deleted the doc-copy-console branch August 12, 2024 07:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants