docs: miscellaneous edits throughout for style and wording #660
Conversation
| @@ -213,10 +208,8 @@ about: | |||
| documentation: https://rich.readthedocs.io | |||
| repository: https://github.com/Textualize/rich | |||
| ``` | |||
| </details> | |||
There was a problem hiding this comment.
I removed the <details> collapsible section tags because it wasn't displaying properly on the docs site (the repo's top-level README.md is fine, however). The monospace words (anything wrapped in a "`") weren't showing up as monospaced and also the filenames were off on their own and not showing up in bold. I tried editing this in multiple ways to keep it collapsible, but no matter what I tried it never seemed to render properly.
Please reference the screenshot below for what I mean:
|
|
||
| #### Usage | ||
|
|
||
| This is useful when you have the project description in a well defined project file, such as, `Cargo.toml`, `package.json`, `pyproject.toml`, `package.yaml`, or `stack.yaml`. And would like to keep the recipe as simple as possible, while not worrying about keeping changes in sync, perhaps using it with CI/CD. | ||
| `load_from_file` is useful when there is a project description in a well-defined project file such as `Cargo.toml`, `package.json`, `pyproject.toml`, `package.yaml`, or `stack.yaml`. It enables the recipe to be preserved in as simple a state as possible, especially when there is no need to keep the changes in sync; some example use cases for this are with CI/CD infrastructure or when there is a well-defined output format. |
There was a problem hiding this comment.
This paragraph needs double-checking; I want to confirm that the edited wording is still true to the original meaning.
| @@ -97,5 +93,4 @@ source: | |||
| tag: ${{ latest_tag }} | |||
| ``` | |||
|
|
|||
| Though it's important to understand currently we don't guarantee caching for repo fetch for git functions | |||
| this may lead to some performance issues. | |||
| There is currently no guarantee of caching for repo fetches when using `git` functions. This may lead to some performance issues. | |||
There was a problem hiding this comment.
Requesting a confirmation to make sure that the rewording is still accurate here.
| @@ -229,7 +228,7 @@ source: | |||
| ``` | |||
|
|
|||
| Note: `tag` or `rev` may not be available within commit depth range, hence we don't | |||
| allow using `rev` or `tag` and `depth` of them together if not set to `-1`. | |||
| allow using `rev` or the `tag` and `depth` of them together if not set to `-1`. | |||
There was a problem hiding this comment.
I found the original sentence to be a bit confusing but I'm still not 100% sure that this edit makes sense.
| Versions for requirements must follow the conda/mamba match specification. See | ||
| build-version-spec. | ||
| Versions for requirements must follow the `conda`/`mamba` match specification. See | ||
| `build-version-spec`. |
There was a problem hiding this comment.
Should build-version-spec here be a link?
|
One other thing I noticed is that the links don't show up as differentiated text in lightmode vs nightmode. Please see the below screenshots for what I mean: lightmode nightmode If this is enough of a concern, I'm happy to file an issue. |
|
Looks great! Thanks so much for your edits. I'll fix teh link color in light mode right away :) |
My initial intention was to only read through/edit the Advanced Build Options section but then I ended up reading through and editing all of the docs pages. 😆
Please feel free to take or leave some of the more minor edits. However, there are some questions that popped up in regards to wording/clarification, which I will point out via comments to this PR.
Thank you to the folks at prefix.dev and other
rattler-buildcontributors for providing such detailed and helpful documentation with so many examples! 👍 👍