Skip to content
This repository has been archived by the owner on Aug 1, 2024. It is now read-only.

Fix a minor typo in README.md #124

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

vvv
Copy link

@vvv vvv commented Mar 11, 2023

No description provided.

@pksunkara
Copy link
Contributor

This might be intentional for docs.rs example?

@yaahc
Copy link
Collaborator

yaahc commented Aug 16, 2023

This might be intentional for docs.rs example?

I think you're correct. I usually edit the lib.rs top level doc comment and then copy it back into the readme to keep them in lock step. I don't have any objections to changing the github readme to not comment this out since it only adds visual noise in that location, but in the future we should probably automate the process of keeping the two copies in sync better and apply any logic that customizes one vs the other two that system (whatever it ends up looking like, whether its a script or some instructions in documentation).

@pksunkara
Copy link
Contributor

If we want to just to keep it in sync, #![doc = include_str!("README.md")] is easy, but it does not allow any customization IIUC.

@yaahc
Copy link
Collaborator

yaahc commented Aug 16, 2023

If we want to just to keep it in sync, #![doc = include_str!("README.md")] is easy, but it does not allow any customization IIUC.

oh, yeah actually there's more difference than I initially remembered. Github doesn't allow some of the same html/css shenanigans that docs.rs does, so I have to use screenshots to give nice colored output in the readme, but for docs.rs I use "copy as html" from the output in gnome terminal to have the text match the rest of the docs. I feel like that's a super nice property that I wouldn't want to use, otherwise I'd love to use the include_str approach.

@vvv
Copy link
Author

vvv commented Aug 17, 2023

This might be intentional for docs.rs example?

Oh. I wasn't aware of this peculiarity of docs.rs.

Shall we close the PR then?

@yaahc
Copy link
Collaborator

yaahc commented Sep 4, 2023

Shall we close the PR then?

No, I think it's fine for now, we just may have to fix this again in the future if it accidentally get's reintroduced. Long term I'd like to automate the process of keeping them in sync somehow.

Copy link

@thenorili thenorili left a comment

Choose a reason for hiding this comment

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

It's good in Jane's book, so it's good in mine. I've opened issue #143 tracking the intention to automate synchronization between docs.rs and the README.md.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants