|
| 1 | +# Scala3doc |
| 2 | + |
| 3 | +Scala3doc (name subject to change) is the documentation tool for |
| 4 | +[Dotty](https://github.com/lampepfl/dotty), which is scheduled to become |
| 5 | +Scala 3. It's based on [Dokka](https://github.com/Kotlin/dokka), the |
| 6 | +documentation tool for Kotlin. It uses Tasty-Reflect to access definitions, |
| 7 | +which is an officially supported way to access Dotty's perspective of a |
| 8 | +codebase. |
| 9 | + |
| 10 | +We're aiming to support all the features Scaladoc did, plus new and exciting ones such as: |
| 11 | + |
| 12 | +- Markdown syntax! |
| 13 | +- displaying project and API documentation together on one site! |
| 14 | +- and more! |
| 15 | + |
| 16 | +## Running the project |
| 17 | + |
| 18 | +Use the following commands to generate documentation for this project and for Dotty, respectively: |
| 19 | + |
| 20 | +``` |
| 21 | +sbt generateSelfDocumentation |
| 22 | +sbt generateDottyLibDocumentation |
| 23 | +``` |
| 24 | + |
| 25 | +To actually view the documentation, the easiest way is to run the following in project root: |
| 26 | + |
| 27 | +``` |
| 28 | +cd output |
| 29 | +python3 -m http.server 8080 |
| 30 | +``` |
| 31 | + |
| 32 | +And afterwards point your browser to `http://localhost:8080/self` or |
| 33 | +`http://localhost:8080/stdLib` for this project and for Dotty documentation |
| 34 | +respectively. |
| 35 | + |
| 36 | +It's not strictly necessary to go through an HTTP server, but because of CORS |
| 37 | +the documentation won't work completely if you don't. |
| 38 | + |
| 39 | +## Developing |
| 40 | + |
| 41 | +At least two of our contributors use [Metals](https://scalameta.org/metals/) to |
| 42 | +work on the project. |
| 43 | + |
| 44 | +For every PR, we build documentation for Scala3doc and Dotty. For example, for |
| 45 | +PR 123 you can find them at: |
| 46 | + |
| 47 | ++ https://scala3doc.s3.eu-central-1.amazonaws.com/pr-123/self/main/index.html |
| 48 | ++ https://scala3doc.s3.eu-central-1.amazonaws.com/pr-123/stdLib/main/index.html |
| 49 | + |
| 50 | +Note that these correspond to the contents of `output` directory - that's |
| 51 | +precisely what they are. |
| 52 | + |
| 53 | +You can also find the result of building the same sites for latest `master` at: |
| 54 | + |
| 55 | ++ https://scala3doc.s3.eu-central-1.amazonaws.com/pr-master/self/main/index.html |
| 56 | ++ https://scala3doc.s3.eu-central-1.amazonaws.com/pr-master/stdLib/main/index.html |
| 57 | + |
| 58 | +### Testing |
| 59 | + |
| 60 | +Most tests rely on comparing signatures (of classes, methods, objects etc.) extracted from the generated documentation |
| 61 | +to signatures found in source files. Such tests are defined using [MultipleFileTest](src/test/scala/dotty/dokka/MultipleFileTest.scala) class |
| 62 | +and its subtypes (such as [SingleFileTest](src/test/scala/dotty/dokka/SingleFileTest.scala)) |
| 63 | + |
| 64 | +WARNING: As the classes mentioned above are likely to evolve, the description below might easily get out of date. |
| 65 | +In case of any discrepancies rely on the source files instead. |
| 66 | + |
| 67 | +`MultipleFileTest` requires that you specify the names of the files used to extract signatures, |
| 68 | +the names of directories containing corresponding TASTY files |
| 69 | +and the kinds of signatures from source files (corresponding to keywords used to declare them like `def`, `class`, `object` etc.) |
| 70 | +whose presence in the generated documentation will be checked (other signatures, when missing, will be ignored). |
| 71 | +The mentioned source files should be located directly inside `src/main/scala/tests` directory |
| 72 | +but the file names passed as parameters should contain neither this path prefix nor `.scala` suffix. |
| 73 | +The TASTY folders are expected to be located in `target/${dottyVersion}/classes/tests` (after successful compilation of the project) |
| 74 | +and similarly only their names relative to this path should be provided as tests' parameters. |
| 75 | +For `SingleFileTest` the name of the source file and the TASTY folder are expected to be the same. |
| 76 | + |
| 77 | +By default it's expected that all signatures from the source files will be present in the documentation |
| 78 | +but not vice versa (because the documentation can contain also inherited signatures). |
| 79 | +To validate that a signature present in the source does not exist in the documentation |
| 80 | +(because they should be hidden from users) add `//unexpected` comment after the signature in the same line. |
| 81 | +This will cause an error if a signature with the same name appears in the documentation |
| 82 | +(even if some elements of the signature are slightly different - to avoid accidentally passing tests). |
| 83 | +If the signature in the documentation is expected to slightly differ from how it's defined in the source code |
| 84 | +you can add a `//expected: ` comment (also in the same line and followed by a space) followed by the expected signature. |
| 85 | +Alternatively you can use `/*<-*/` and `/*->*/` as opening and closing parentheses for parts of a signature present in the source but undesired in the documentation (at least at the current stage of development), e.g. |
| 86 | + |
| 87 | +``` |
| 88 | +def foo/*<-*/()/*->*/: Int |
| 89 | +``` |
| 90 | + |
| 91 | +will make the expected signature be |
| 92 | + |
| 93 | +``` |
| 94 | +def foo: Int |
| 95 | +``` |
| 96 | + |
| 97 | +instead of |
| 98 | + |
| 99 | +``` |
| 100 | +def foo(): Int |
| 101 | +``` |
| 102 | + |
| 103 | + |
| 104 | +Because of the way how signatures in source are parsed, they're expected to span until the end of a line (including comments except those special ones mentioned above, which change the behaviour of tests) so if a definition contains an implementation, it should be placed in a separate line, e.g. |
| 105 | + |
| 106 | +``` |
| 107 | +def foo: Int |
| 108 | + = 1 |
| 109 | +
|
| 110 | +class Bar |
| 111 | +{ |
| 112 | + //... |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +Otherwise the implementation would be treated as a part of the signature. |
| 117 | + |
| 118 | +## Roadmap |
| 119 | + |
| 120 | +1. Publish an initial version of the tool together with an SBT plugin |
| 121 | +1. Replace Dottydoc as the dedicated tool for documenting Dotty code |
| 122 | + |
| 123 | + This includes: |
| 124 | + + supporting Dotty's doc pages |
| 125 | + + releasing together with Dotty as the dedicated documentation tool |
| 126 | + |
| 127 | +1. Support all kinds of Dotty definition and generate documentation for the |
| 128 | + standard library |
| 129 | +1. Reach feature parity with Scaladoc |
| 130 | + |
| 131 | +## Contributing |
| 132 | + |
| 133 | +We're happy that you'd like to help us! |
| 134 | + |
| 135 | +We have two issue labels you should take a look at: `good first issue` and |
| 136 | +`self-contained`. First is easy pickings: you'll be able to contribute without |
| 137 | +needing to dive too deep into the project. Second is reverse: it's an issue |
| 138 | +that's you may find interesting, complex and self-contained enough that you can |
| 139 | +continue chipping away at it without needing to worry too much about merge |
| 140 | +conflicts. |
| 141 | + |
| 142 | +To contribute to the project with your code, fork this repo and create a pull request from a fresh branch from there. |
| 143 | +To keep the history of commits clean, make sure your commits are squashed into one |
| 144 | +and all your changes are applied on top of the latest master branch (if not - rebase on it instead of merging it). |
| 145 | +Make sure all the tests pass (simply run `sbt test` to verify that). |
| 146 | + |
| 147 | +## FAQ |
| 148 | + |
| 149 | +### Why depend on Dokka? |
| 150 | + |
| 151 | +We have two primary reasons for depending on Dokka. One of them is division of |
| 152 | +labour - Dokka already has a team of maintainers, and it supports an excellent |
| 153 | +API which already allowed us to quite easily generate documentation with it. By |
| 154 | +depending on Dokka, we will be able to share a large portion of the maintenance |
| 155 | +burden. The second reason is very pragmatic - on our own, it'd be difficult for |
| 156 | +us to reach even feature parity with Scaladoc, simply because of workforce |
| 157 | +constraints. Meanwhile, Dokka maintainers from VirtusLab reached out to us with |
| 158 | +an offer of help, which we were happy to take. |
| 159 | + |
| 160 | +### Why use TASTy? |
| 161 | + |
| 162 | +A documentation tool needs to access compiler information about the project - it |
| 163 | +needs to list all definitions, resolve them by name, and query their members. |
| 164 | +Tasty Reflect is the dedicated way in Scala 3 of accessing this information. |
0 commit comments