Improvements to documentation #12712

eth3lbert · 2024-08-06T09:49:06Z

Summary

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

eth3lbert · 2024-08-06T09:50:35Z

docs/requirements.txt

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

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.

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.

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

I think it's mkdocs>=1.5.0 which would install 1.6.0 if possible: https://github.com/astral-sh/uv/blob/d0b16f90185ca7783d114306ade1626156ea6e29/docs/requirements.in#L2

Yes, but not for the insiders version? It uses the same commit as ruff. https://github.com/astral-sh/uv/blob/d0b16f90185ca7783d114306ade1626156ea6e29/docs/requirements-insiders.txt#L71-L76

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.

Fair enough!

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

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

eth3lbert · 2024-08-06T10:07:05Z

\cc @zanieb

eth3lbert · 2024-08-06T10:10:14Z

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

github-actions · 2024-08-06T10:21:47Z

`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

MichaReiser

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?

MichaReiser · 2024-08-06T19:43:27Z

README.md

-```shell
-# With pip.
-pip install ruff
+```console


Does this change how github or pypi renders the readme?

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?

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

~~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

MichaReiser · 2024-08-07T06:59:51Z

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

MichaReiser · 2024-08-07T07:44:06Z

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

MichaReiser · 2024-08-07T07:49:00Z

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

MichaReiser · 2024-08-07T07:50:29Z

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://git@github.com/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 · 2024-08-07T08:07:54Z

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

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.

eth3lbert · 2024-08-09T16:31:32Z

docs/js/extra.js

+    const start = performance.now();
+


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

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

eth3lbert · 2024-08-09T16:31:45Z

docs/js/extra.js

@@ -37,6 +39,8 @@ function setCopyText() {
        );
      }
    });
+
+    console.log(performance.now() - start);


MichaReiser · 2024-08-12T07:13:29Z

The trick is to not upgrade mkdocs-material

eth3lbert · 2024-08-12T07:20:59Z

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

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

eth3lbert requested a review from MichaReiser as a code owner August 6, 2024 09:49

eth3lbert commented Aug 6, 2024

View reviewed changes

MichaReiser reviewed Aug 6, 2024

View reviewed changes

MichaReiser added the documentation Improvements or additions to documentation label Aug 7, 2024

eth3lbert requested a review from MichaReiser August 7, 2024 07:21

eth3lbert commented Aug 9, 2024

View reviewed changes

dhruvmanila mentioned this pull request Aug 12, 2024

Update dependency mkdocs to v1.6.0 #12828

Merged

1 task

eth3lbert added 3 commits August 12, 2024 08:58

Improve copy of console command examples

370a6c1

Improvements to the documentation

2232531

Allow dollar sign

93e09a7

MichaReiser force-pushed the doc-copy-console branch from bb6f4e1 to 93e09a7 Compare August 12, 2024 07:09

MichaReiser added 2 commits August 12, 2024 09:09

Discard changes to CONTRIBUTING.md

6ef4efa

Don't setup observe if page has no code blocks

6233a53

MichaReiser enabled auto-merge (squash) August 12, 2024 07:13

MichaReiser merged commit 59f712a into astral-sh:main Aug 12, 2024
16 checks passed

eth3lbert deleted the doc-copy-console branch August 12, 2024 07:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improvements to documentation #12712

Improvements to documentation #12712

eth3lbert commented Aug 6, 2024

eth3lbert Aug 6, 2024

dhruvmanila Aug 7, 2024

eth3lbert Aug 7, 2024

MichaReiser Aug 7, 2024

dhruvmanila Aug 7, 2024

MichaReiser Aug 9, 2024 •

edited

Loading

MichaReiser Aug 9, 2024

eth3lbert Aug 9, 2024

MichaReiser Aug 9, 2024

eth3lbert Aug 9, 2024

eth3lbert commented Aug 6, 2024

eth3lbert commented Aug 6, 2024

github-actions bot commented Aug 6, 2024 •

edited

Loading

MichaReiser left a comment

MichaReiser Aug 6, 2024

eth3lbert Aug 7, 2024

MichaReiser Aug 7, 2024

eth3lbert Aug 7, 2024 •

edited

Loading

MichaReiser commented Aug 7, 2024

MichaReiser commented Aug 7, 2024

MichaReiser commented Aug 7, 2024

MichaReiser commented Aug 7, 2024 •

edited

Loading

eth3lbert commented Aug 7, 2024 •

edited

Loading

eth3lbert Aug 9, 2024

MichaReiser Aug 9, 2024

eth3lbert Aug 9, 2024

MichaReiser commented Aug 12, 2024

eth3lbert commented Aug 12, 2024

Improvements to documentation #12712

Improvements to documentation #12712

Conversation

eth3lbert commented Aug 6, 2024

Summary

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MichaReiser Aug 9, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eth3lbert commented Aug 6, 2024

eth3lbert commented Aug 6, 2024

github-actions bot commented Aug 6, 2024 • edited Loading

ruff-ecosystem results

Linter (stable)

Linter (preview)

Formatter (stable)

Formatter (preview)

MichaReiser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eth3lbert Aug 7, 2024 • edited Loading

Choose a reason for hiding this comment

MichaReiser commented Aug 7, 2024

MichaReiser commented Aug 7, 2024

MichaReiser commented Aug 7, 2024

MichaReiser commented Aug 7, 2024 • edited Loading

eth3lbert commented Aug 7, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MichaReiser commented Aug 12, 2024

eth3lbert commented Aug 12, 2024

MichaReiser Aug 9, 2024 •

edited

Loading

github-actions bot commented Aug 6, 2024 •

edited

Loading

`ruff-ecosystem` results

eth3lbert Aug 7, 2024 •

edited

Loading

MichaReiser commented Aug 7, 2024 •

edited

Loading

eth3lbert commented Aug 7, 2024 •

edited

Loading