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

Add docs url for all functions in Glossary page #4444

Open
lenguyenthanh opened this issue May 26, 2023 · 8 comments
Open

Add docs url for all functions in Glossary page #4444

lenguyenthanh opened this issue May 26, 2023 · 8 comments
Assignees

Comments

@lenguyenthanh
Copy link
Member

This page is awesome: https://typelevel.org/cats/nomenclature.html. But I think it'll be better if we add docs url to all functions.

For example:

| `F[A] => F[Unit]`  | `void`   |

To

| `F[A] => F[Unit]`  | `[void](https://www.javadoc.io/doc/org.typelevel/cats-docs_2.13/latest/cats/Functor.html#void[A](fa:F[A]):F[Unit])`   |

If this is something we accept, I can work on this.

@armanbilge
Copy link
Member

Thank you, that sounds good to me! I wonder if we should add an example of how to use it with syntax as well? Since it's a bit different than calling the method directly on the typeclass.

@lenguyenthanh
Copy link
Member Author

lenguyenthanh commented May 26, 2023

I guess we can add examples, but it can be convoluted, which is opposite to the purpose of this page which in turn to give an overview of all the type classes.

I think if we have examples in the java doc, for each function is enough. wdyt?

@armanbilge
Copy link
Member

I think if we have examples in the java doc, for each example is enough. wdyt?

good point! :)

@lenguyenthanh
Copy link
Member Author

I did add some link here https://github.com/lenguyenthanh/cats/blob/add-links-for-glossary-page/docs/nomenclature.md.

But there are few issues, I can see right away (and not sure how to fix):

@armanbilge
Copy link
Member

armanbilge commented Jun 13, 2023

  • We have to keep update the docs url with scala version and cats version.

We can use @VERSION@ mdoc variable to keep the Cats version in sync. What if we link to the Scala 3 docs, does that work for going straight to the function?

  • CI failed at generating the site

Hmmm. I wonder if it helps to put the links at the bottom of the doc instead of inline.

Thanks for your work on this!!

@lenguyenthanh
Copy link
Member Author

thanks!
The scala 3 docs version works 💯

I also tried @VERSION@ with hope that mdoc works, because the scala 3 docs url is much simpler than the scala 2 docs with a lot of [][][][] :D

@lenguyenthanh
Copy link
Member Author

after switching to scala 3 docs url, everything passes: https://github.com/lenguyenthanh/cats/actions/runs/5259440112

But I can't build the site locally. Both docs/tlSitePreview and docs/tlSite shutdown the sbt after a lot of warning like this: https://gist.github.com/lenguyenthanh/df88115b7af5b974d0324c3c2a712df6

But they did generate md files in site/target/mdoc, and the generated files look correct.

@armanbilge
Copy link
Member

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

No branches or pull requests

2 participants