Migrate website to docusaurus #808

olafurpg · 2018-08-22T13:17:44Z

This commit migrates the site to use docusaurus, which has the following
benefits:

around 10x faster preview while typing documentation. Changes usually
render within ~500ms with automatic browser reload after file save
compared to ~10-20 second latency in the previous setup.
splashy landing page

Big thanks to @gabro for setting up the first Docusaurus website for Metals https://scalameta.org/metals/

This commit migrates the site to use docusaurus, which has the following benefits: - around 10x faster preview while typing documentation. Changes usually render within ~500ms with automatic browser reload after file save compared to ~10-20 second latency in the previous setup. - splashy landing page

olafurpg · 2018-08-22T13:21:04Z

Small preview of how the new website looks like. It will not go live until v0.6.0-RC1 is released. The actual contents and section organization will require further polish first. This PR only migrates contents from the old website to the new setup.

codecov · 2018-08-22T13:28:39Z

Codecov Report

Merging #808 into master will increase coverage by 0.96%.
The diff coverage is 96.29%.

@@            Coverage Diff             @@
##           master     #808      +/-   ##
==========================================
+ Coverage   71.58%   72.55%   +0.96%     
==========================================
  Files         154      158       +4     
  Lines        3801     3869      +68     
  Branches      336      331       -5     
==========================================
+ Hits         2721     2807      +86     
+ Misses       1080     1062      -18

Impacted Files	Coverage Δ
...a/scalafix/internal/rule/ExplicitResultTypes.scala	`87.83% <ø> (ø)`	⬆️
...cli/src/main/scala/scalafix/internal/v1/Args.scala	`87.87% <100%> (ø)`	⬆️
...alafix-docs/src/main/scala/docs/HelpModifier.scala	`100% <100%> (ø)`
scalafix-docs/src/main/scala/docs/Main.scala	`100% <100%> (ø)`
...lafix-docs/src/main/scala/docs/RulesModifier.scala	`100% <100%> (ø)`
scalafix-docs/src/main/scala/docs/website.scala	`95.65% <85.71%> (ø)`
... and 2 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 247c781...445dfe1. Read the comment docs.

gabro · 2018-08-22T13:33:13Z

build.sbt

-      core
+    libraryDependencies ++= List(
+      "com.geirsson" %% "metaconfig-docs" % metaconfigV,
+      "com.geirsson" % "mdoc" % "0.4.0" cross CrossVersion.full,


do you need the explicit mdoc dependency even when using the DocusaursPlugin?

gabro · 2018-08-22T13:34:01Z

docs/rule-authors/setup.md


- Assert that a {% glossary_ref LintMessage %} is expected at a particular line by suffixing the line with the comment `// assert: <LintCategory>`. For an example, see the NoInfer test suite:
+- Assert that a {% glossary_ref LintMessage %} is expected at a particular line


These refs are now unhandled.

gabro · 2018-08-22T13:34:58Z

docs/rules/DisableSyntax.md

@@ -1,15 +1,12 @@
 ---
 layout: docs


it doesn't harm, but you don't need layout anymore md files

gabro · 2018-08-22T13:36:16Z

scalafix-docs/src/main/scala/docs/RulesModifier.scala

+      code: Input,
+      reporter: Reporter
+  ): String = {
+    scalafix.website.allRulesTable(reporter)


As discussed offline, I would suggest to make this a variable, since it doesn't depend on the code block content (which is, in fact, empty)

This uses the reporter to warn about missing documentation so I prefer to keep it as a modifier

gabro · 2018-08-22T13:38:12Z

website/siteConfig.js

+  organizationName: "scalacenter",
+
+  algolia: {
+    apiKey: "???",


you may want to remove the algolia section until you have a valid API, so that the search bar doesn't appear

MasseGuillaume · 2018-08-22T13:32:40Z

website/pages/en/index.js

+);
+
+const Features = props => {
+  const features = [


img should have alt

for reference, the props is called imageAlt (it's passed down to GridBlock)

MasseGuillaume · 2018-08-22T13:33:14Z

website/sidebars.json

+      "rule-authors/glossary"
+    ]
+  },
+  "rules": {


Can we generate this?

We can, but it's simplest to keep it manual for now. Ideally, I want docs.Main to take care of generating data like this and also start the live reload server.

MasseGuillaume · 2018-08-22T13:37:07Z

website/pages/en/index.js

+    {
+      title: "Extensible",
+      content: "Extend Scalafix with custom rewrite and linting rules",
+      image: imgUrl("extensible.png"),


I would prefer we avoid using image for this feature. We cannot copy paste, it's not super accessible. I can do a followup PR for this.

Let's improve the landing page in a followup PR

MasseGuillaume · 2018-08-22T13:40:59Z

docs/users/installation.md

+| Scalafix Version | Scalameta(SemanticDB) Version | Scala Version           |
+| ---------------- | ----------------------------- | ----------------------- |
+| 0.5.10           | 2.1.7                         | 2.11.12 / 2.12.4        |
+| @VERSION@        | @SCALAMETA@                   | @SCALA211@ / @SCALA212@ |


This is pain point number one. I would prefer we release a Scalameta version for each Scala Version. I think we discussed this offline and you said it would be to much work. We should make it really clear here what is supported.

In hindsight, we should have forward ported semanticdb 2.1.7 to 2.12.6 once it came out. This was a special çase however, not even Scala.js forward ports outdated releases for new Scala compiler versions. I did not anticipate it would take this long to get Scalameta v4.0 out and I agree it's caused pain point for users.

As for publishing SemanticDB for 2.12.4 and older versions I'm not convinced it's worth the cost and I haven't seen many requests for this.

MasseGuillaume · 2018-08-22T13:42:33Z

docs/users/installation.md

+
+```scala
+// project/plugins.sbt
+addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "@VERSION@")


This is incorrect. Right now I see: 0.5.10 + Scala 2.12.6.

That's because 0.5.10 is still the "stable version" until at least v0.6.0-RC1 is released.

MasseGuillaume · 2018-08-22T13:46:41Z

docs/users/installation.md

+    "-Ywarn-unused-import" // required by `RemoveUnusedImports` rule
+  )
+)
+


split code block

MasseGuillaume · 2018-08-22T13:47:37Z

docs/users/installation.md

+
+## Command line
+
+The recommended way to install the scalafix command-line interface is with


I would remove recommended, since it's the only sane way to install the cli.

Good catch, previously there were several alternatives to install the cli (homebrew, wget). Coursier only is simpler.

MasseGuillaume · 2018-08-22T13:48:01Z

docs/users/installation.md

+## Maven
+
+It is possible to use scalafix with scala-maven-plugin but it requires a custom
+setup since there is no scalafix specific Maven plugin.


Help wanted?

Updated. Also improved the Maven section a bit more.

MasseGuillaume · 2018-08-22T13:51:20Z

docs/users/installation.md

+If using the sbt plugin
+
+```scala
+// project/plugins.sbt


We can get this version with a small javascript snippet: scalacenter/bloop#374

Cool, we can do that in a separate PR

MasseGuillaume · 2018-08-22T13:52:48Z

docs/users/installation.md

+
+### --help
+
+```scala mdoc:--help


--help is not formatted properly since it's a scala code block.

As discussed offline, I would make this a variable instead of a code block.

@MasseGuillaume the rendered block will not have the scala language. mdoc should support any language so it's possible to either skip the language prefix or do sh mdoc. I opened https://github.com/olafurpg/mdoc/issues/57

@gabro If we make --help a site variable then positions will be messed up for the rest of the document since we search/replace site variables before parsing the markdown document with flexmark. Site variables should be single-line only. Maybe we can come up with a better solution, but until then I think having a custom modifier is best.

olafurpg

Thank you @gabro and @MasseGuillaume for the review!

olafurpg · 2018-08-22T15:50:34Z

docs/users/installation.md

+| Scalafix Version | Scalameta(SemanticDB) Version | Scala Version           |
+| ---------------- | ----------------------------- | ----------------------- |
+| 0.5.10           | 2.1.7                         | 2.11.12 / 2.12.4        |
+| @VERSION@        | @SCALAMETA@                   | @SCALA211@ / @SCALA212@ |


In hindsight, we should have forward ported semanticdb 2.1.7 to 2.12.6 once it came out. This was a special çase however, not even Scala.js forward ports outdated releases for new Scala compiler versions. I did not anticipate it would take this long to get Scalameta v4.0 out and I agree it's caused pain point for users.

As for publishing SemanticDB for 2.12.4 and older versions I'm not convinced it's worth the cost and I haven't seen many requests for this.

olafurpg · 2018-08-22T15:51:15Z

docs/users/installation.md

+
+```scala
+// project/plugins.sbt
+addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "@VERSION@")


That's because 0.5.10 is still the "stable version" until at least v0.6.0-RC1 is released.

olafurpg · 2018-08-22T15:59:01Z

docs/users/installation.md

+    "-Ywarn-unused-import" // required by `RemoveUnusedImports` rule
+  )
+)
+


olafurpg · 2018-08-22T15:59:45Z

docs/users/installation.md

+
+- The `semanticdb-scalac` compiler plugin produces
+  [SemanticDB](https://github.com/scalameta/scalameta/blob/master/semanticdb/semanticdb3/semanticdb3.md)
+  files in the target directory `META-INF/semanticdb/`. These files are used by


olafurpg · 2018-08-22T16:04:25Z

docs/users/installation.md

+repository.
+
+```scala
+git clone https://github.com/olafurpg/scalafix-sbt-example


Good catch, the repo is already under scalacenter/, was a bad link.

I agree confusing to advertise two different examples. The front page links to the template for rule authors while this is an example for end users. It's best to remove the reference to scalafix.g8 on the landing page and use a better image for "Extensible". It's not possible to have git clone workflow for rule authors since filenames dependent on the project name.

olafurpg · 2018-08-22T16:36:04Z

docs/users/installation.md

+If using the sbt plugin
+
+```scala
+// project/plugins.sbt


Cool, we can do that in a separate PR

olafurpg · 2018-08-22T16:36:49Z

scalafix-docs/src/main/scala/docs/RulesModifier.scala

+      code: Input,
+      reporter: Reporter
+  ): String = {
+    scalafix.website.allRulesTable(reporter)


This uses the reporter to warn about missing documentation so I prefer to keep it as a modifier

olafurpg · 2018-08-22T16:37:00Z

scalafix-docs/src/main/scala/docs/website.scala

-          s"Missing documentation for rule ${rule.name.value} in path $docPath"
-        )
+      if (!Files.isRegularFile(docPath.toNIO)) {
+        reporter.warning(s"Missing $docPath")


olafurpg · 2018-08-22T16:37:30Z

website/pages/en/index.js

+    {
+      title: "Extensible",
+      content: "Extend Scalafix with custom rewrite and linting rules",
+      image: imgUrl("extensible.png"),


Let's improve the landing page in a followup PR

olafurpg · 2018-08-22T16:38:28Z

website/sidebars.json

+      "rule-authors/glossary"
+    ]
+  },
+  "rules": {


We can, but it's simplest to keep it manual for now. Ideally, I want docs.Main to take care of generating data like this and also start the live reload server.

olafurpg · 2018-08-22T19:47:54Z

Merging to unblock a PR updating the v1 API. We can iterate on the contents and structure separately, nothing goes live here.

Comments addressed

olafurpg force-pushed the docusaurus branch from 5c50c16 to 2901d44 Compare August 22, 2018 13:18

olafurpg requested a review from MasseGuillaume August 22, 2018 13:21

gabro reviewed Aug 22, 2018

View reviewed changes

docs/rules/DisableSyntax.md

@@ -1,15 +1,12 @@

---

layout: docs

Copy link

Collaborator

gabro Aug 22, 2018

Choose a reason for hiding this comment

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

it doesn't harm, but you don't need layout anymore md files

gabro reviewed Aug 22, 2018

View reviewed changes

MasseGuillaume previously requested changes Aug 22, 2018

View reviewed changes

Address review feedback

445dfe1

olafurpg commented Aug 22, 2018

View reviewed changes

olafurpg merged commit 1d9d610 into scalacenter:master Aug 22, 2018

olafurpg deleted the docusaurus branch August 22, 2018 19:48

This was referenced Aug 27, 2018

Website css on mobile #396

Closed

More slick landing page #391

Closed


		- Assert that a {% glossary_ref LintMessage %} is expected at a particular line by suffixing the line with the comment `// assert: <LintCategory>`. For an example, see the NoInfer test suite:
		- Assert that a {% glossary_ref LintMessage %} is expected at a particular line


		## Command line

		The recommended way to install the scalafix command-line interface is with


		### --help

		```scala mdoc:--help

Migrate website to docusaurus #808

Migrate website to docusaurus #808

Conversation

olafurpg commented Aug 22, 2018

olafurpg commented Aug 22, 2018

codecov bot commented Aug 22, 2018 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

olafurpg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

olafurpg commented Aug 22, 2018

codecov bot commented Aug 22, 2018 •

edited

Loading