Skip to content

minor improvements to developer docs for Scaladoc tool #16769

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Jul 13, 2023
Merged

minor improvements to developer docs for Scaladoc tool #16769

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 12 additions & 20 deletions docs/_docs/contributing/scaladoc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ layout: doc-page
title: Scaladoc
---

Scaladoc is the documentation tool for [Scala
Scaladoc is the documentation tool for [Scala
3](https://github.com/lampepfl/dotty). It uses the TastyInspector to access
definitions, which is an officially supported way to access Scala 3's
perspective of a codebase.
Expand Down Expand Up @@ -62,11 +62,20 @@ You can also find the result of building the same sites for latest `master` at:
- <https://scala3doc.virtuslab.com/master/scala3/main/index.html>
- <https://scala3doc.virtuslab.com/master/testcases/main/index.html>

You can run the Scaladoc tool from the sbt prompt as a user would run it
with `scaladoc/run`, passing `-d <directory>` and some `.tasty` files as
input on the command line.

### Testing

From the sbt prompt, `scaladoc/test` runs the tests.

You can also run specific signature tests with `testOnly`,
for example `scaladoc/test *scaladoc.signatures.MarkdownCode`.

Most tests rely on comparing signatures (of classes, methods, objects etc.) extracted from the generated documentation
to signatures found in source files. Such tests are defined using [SignatureTest](test/dotty/tools/scaladoc/signatures/SignatureTest.scala) class
and its subtypes (such as [TranslatableSignaturesTestCases](test/dotty/tools/scaladoc/signatures/TranslatableSignaturesTestCases.scala))
to signatures found in source files (extracted using Scalameta). Such tests are defined using [SignatureTest](test/dotty/tools/scaladoc/signatures/SignatureTest.scala) class
and its subtypes (such as [TranslatableSignaturesTestCases](test/dotty/tools/scaladoc/signatures/TranslatableSignaturesTestCases.scala)). In this style of test, it's not necessary for expected output to be included, because the test is its own specification.

WARNING: As the classes mentioned above are likely to evolve, the description below might easily get out of date.
In case of any discrepancies rely on the source files instead.
Expand Down Expand Up @@ -121,25 +130,8 @@ class Bar

Otherwise the implementation would be treated as a part of the signature.

## Contributing

We're happy that you'd like to help us!

We have two issue labels you should take a look at: `good first issue` and
`self-contained`. First is easy pickings: you'll be able to contribute without
needing to dive too deep into the project. Second is reverse: it's an issue
that's you may find interesting, complex and self-contained enough that you can
continue chipping away at it without needing to worry too much about merge
conflicts.

To contribute to the project with your code, fork this repo and create a pull request from a fresh branch from there.
To keep the history of commits clean, make sure your commits are squashed into one
and all your changes are applied on top of the latest master branch (if not - rebase on it instead of merging it).
Make sure all the tests pass (simply run `sbt test` to verify that).

## FAQ


### Why use TASTy?

A documentation tool needs to access compiler information about the project - it
Expand Down
4 changes: 2 additions & 2 deletions docs/_docs/contributing/sending-in-a-pr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,11 +138,11 @@ Request](https://help.github.com/articles/using-pull-requests) on GitHub.
If you're not actually finished yet and are just looking for some initial input
on your approach, feel free to open a [Draft PR][draft]. This lets reviewers
know that you're not finished yet. It's also a good idea to put a [wip] in front
of your pr title to make this extra clear.
of your PR title to make this extra clear.

Shortly after creating your pull request a maintainer should assign someone to
review it. If this doesn't happen after a few days, feel free to ping someone on
the [Scala Contributors Discor][discord] or tag someone on the PR. Depending on
the [Scala Contributors Discord][discord] or tag someone on the PR. Depending on
the type of pull request there might be multiple people that take a look at your
changes. There might also be community input as we try to keep the review
process as open as possible.
Expand Down
4 changes: 4 additions & 0 deletions docs/_docs/contributing/testing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,10 @@ sbt:scala3> scala3-compiler/Test/runMain

then compare the changes via version control.

### Scaladoc tests

See the [Scaladoc contributors guide](./scaladoc.md).

## Troubleshooting

Some of the tests depend on temporary state stored in the `out` directory. In rare cases, that directory
Expand Down