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

docs: add initial Kotlin docs #16304

Merged
merged 2 commits into from
Jul 27, 2022
Merged

docs: add initial Kotlin docs #16304

merged 2 commits into from
Jul 27, 2022

Conversation

tdyas
Copy link
Contributor

@tdyas tdyas commented Jul 26, 2022

Add an initial set of docs for the experimental Kotlin backend.

[ci skip-rust]

[ci skip-build-wheels]

excerpt: "Kotlin support for Pants."
hidden: false
---

Copy link
Member

@stuhood stuhood Jul 26, 2022

Choose a reason for hiding this comment

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

This page is very, very similar to the existing Java/Scala page, which is a good sign!

But... rather than duplicating it, it would probably be good to extract the shared portion into a JVM overview page, and then have small pages for Kotlin, Scala, Java that highlight only the differences?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

While I would support such a refactor of the docs, I don't really have the time to devote to such a docs refactor. So I'll start with a Kotlin page in this PR so at least we have a place to link to in a Kotlin blog post with the 2.13 release.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

(Also, a follow-up to this PR will add docs on kotlinc plugins.)

Copy link
Contributor

Choose a reason for hiding this comment

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

I continue to lean towards the best approach being something like Sphinx that lets us reuse the same docs snippet in multiple places.

Duplication can be a good thing in docs -- users don't have to see things that aren't relevant to them, and we make our advice more localized. But it's a maintenance burden, so -> Sphinx

Copy link
Contributor Author

Choose a reason for hiding this comment

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

These docs are markdown though, right? Where are Sphinx docs in the repo?

Copy link
Contributor

Choose a reason for hiding this comment

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

We are not using sphinx yet, but it is planned as future work

Copy link
Contributor

Choose a reason for hiding this comment

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

Generally speaking, I'd prefer the docs to be repetitive, so that you can scan through one page to get an idea of how things work. The high granularity of e.g. our onboarding docs was noted as a barrier to entry at PyCon sprints.

Copy link
Contributor

@Eric-Arellano Eric-Arellano left a comment

Choose a reason for hiding this comment

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

Thanks Tom! Looks great :)

We probably want to mention tailor, although that's fine to be a follow up if you don't have more time. Maybe create a ticket so we can track that.

docs/markdown/Java and Scala/kotlin.md Outdated Show resolved Hide resolved
docs/markdown/Java and Scala/kotlin.md Outdated Show resolved Hide resolved
docs/markdown/Java and Scala/kotlin.md Outdated Show resolved Hide resolved
docs/markdown/Java and Scala/kotlin.md Outdated Show resolved Hide resolved
docs/markdown/Java and Scala/kotlin.md Outdated Show resolved Hide resolved
docs/markdown/Java and Scala/kotlin.md Show resolved Hide resolved
[ci skip-rust]

[ci skip-build-wheels]
@tdyas
Copy link
Contributor Author

tdyas commented Jul 27, 2022

We probably want to mention tailor, although that's fine to be a follow up if you don't have more time. Maybe create a ticket so we can track that.

Can bring that over in another PR.

[ci skip-rust]

[ci skip-build-wheels]
@tdyas tdyas merged commit 68168d7 into pantsbuild:main Jul 27, 2022
@tdyas tdyas deleted the kotlin_docs branch July 27, 2022 03:23
tdyas pushed a commit to tdyas/pants that referenced this pull request Jul 27, 2022
Add an initial set of docs for the experimental Kotlin backend.

[ci skip-rust]

[ci skip-build-wheels]
tdyas pushed a commit that referenced this pull request Jul 28, 2022
Add an initial set of docs for the experimental Kotlin backend.

[ci skip-rust]

[ci skip-build-wheels]
cczona pushed a commit to cczona/pants that referenced this pull request Sep 1, 2022
Add an initial set of docs for the experimental Kotlin backend.

[ci skip-rust]

[ci skip-build-wheels]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants