Tweak docs

typelevel · Nov 3, 2021 · 44c5b12 · 44c5b12
1 parent 44cb7a2
commit 44c5b12
Show file tree

Hide file tree

Showing 7 changed files with 57 additions and 98 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,8 +1,5 @@
+Release notes are now [published on GitHub](https://github.com/typelevel/spire/releases).
 
-## [Version 0.18.0-M1](https://github.com/typelevel/spire/releases/tag/v0.18.0-M1)
-Spire will support Scala 3 since `v0.18.0` and `v0.18.0-M1` is a pre-release including breaking changes toward 0.18.0. For more detail, visit [Release Note](https://github.com/typelevel/spire/releases/tag/v0.18.0-M1).
-
-Since v0.18.0, we track changes in [github releases page](https://github.com/typelevel/spire/releases).
 ## Version 0.16.1-SNAPSHOT
 
  * Disabled benchmarked depending on Caliper; waiting for migration to a modern benchmarking framework

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -1,6 +1,6 @@
-People are expected to follow the [Scala Code of Conduct](https://www.scala-lang.org/conduct/)
-when discussing Spire on the Github page, in Gitter, the IRC channel,
+People are expected to follow the [Typelevel Code of Conduct](https://typelevel.org/code-of-conduct.html)
+when discussing Spire on the Github page, in Discord, Gitter, the IRC channel,
 mailing list, and other official venues.
 
-Concerns or issues can be sent to any of Spire's maintainers, or to the
-[Typelevel](https://typelevel.org/about.html) organization.
+Concerns or issues can be sent to any of Spire's maintainers, or to any of the
+[designated CoC contacts](https://typelevel.org/code-of-conduct.html) for Typelevel.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -13,22 +13,11 @@ We also gladly accept patches for documentation. Anything from fixing
 a typo to writing a full tutorial is a great way to help the
 project.
 
-#### Quick guide for documentation
-You can directly edit documents at https://github.com/typelevel/spire/tree/main/docs/src/main/mdoc, but it is better to use git to manage diffs.
-
-
-1. Visit https://github.com/typelevel/spire and fork the repository.
-
-2. Clone the forked repository and make new branch.
-
-3. Run `sbt docs/makeMicrosite` to build document website, change directory to `docs/target/site` and run `jekyll serve -b /spire`.
-
-You can preview website at http://localhost:4000/spire by default.
-
-Note: `makeMicrosite` depends on jekyll 4.x. Make sure that you have [jekyll(4+)](https://jekyllrb.com/docs/installation/) in your environment.
-
-Finally, commit your changes and create PR at typelevel/spire repository.
+The documentation lives in the [`docs/src/main/mdoc`](https://github.com/typelevel/spire/tree/main/docs/src/main/mdoc) directory in the repository. To preview the website locally:
 
+1. [Install Jekyll v4](https://jekyllrb.com/docs/installation/).
+2. Run `sbt docs/makeMicrosite`. Change directory to `docs/target/site` and run `jekyll serve -b /spire`.
+3. Preview website at http://localhost:4000/spire.
 
 ### Reporting bugs, issues, or unexpected behavior
 
@@ -53,7 +42,7 @@ other people's opinions.
 
 ### Creating or improving tests
 
-Spire uses [ScalaTest](https://www.scalatest.org) and
+Spire uses [munit](https://scalameta.org/munit/) and
 [ScalaCheck](https://scalacheck.org/) to test our code. The tests
 fulfill a number of important functions:
 
@@ -88,9 +77,11 @@ not to get merged to main as quickly. For this kind of work, you
 should submit a pull request from your branch, but we will probably
 leave the PR open for awhile while commenting on it.
 
-You can always ask questions at [Typelevel Discord](https://discord.com/invite/XF3CXcMzqD) or [Spire gitter](https://gitter.im/typelevel/spire), email the list, or visit the `#spire-math` IRC channel
+You can always message the `#spire` channel on the [Typelevel Discord](typelevel-discord)
 to get a second opinion on your idea or design.
 
+[typelevel-discord]: https://discord.com/invite/XF3CXcMzqD
+
 ### Ask questions and make suggestions
 
 Spire strives to be an excellent part of the Scala ecosystem. We

diff --git a/FRIENDS.md b/FRIENDS.md
@@ -1,13 +1,12 @@
-## Friends of Spire
+Friends of Spire
 ================
 
 Here is a list of libraries that are based on Spire, or have Spire compatibility.
 
 - [Libra](https://to-ithaca.github.io/libra/), dimensional analysis for Scala
-- [coulomb](https://github.com/erikerlandson/coulomb) colomb: unit analysis for Scala
-- [circe-spire](https://github.com/circe/circe-spire) circe codecs for Spire types
+- [coulomb](https://github.com/erikerlandson/coulomb) coulomb: unit analysis for Scala
+- [circe-spire](https://github.com/circe/circe-spire) circe encoders and decoders for Spire types
 - [onnx-scala](https://github.com/EmergentOrder/onnx-scala) An ONNX (Open Neural Network eXchange) API and backend for typeful, functional deep learning in Scala (3)
 - [NDScala](https://github.com/SciScala/NDScala) N-dimensional arrays in Scala 3. Think NumPy ndarray, but with compile-time type-checking/inference over shapes, ndarray/axis labels & numeric data types
 - [Sonic reducer](https://github.com/rklaehn/sonicreducer), Hierarchical reducer for arbitrary Scala sequences
 - [spire-matrix](https://github.com/lJoublanc/spire-matrix), BLAS-backed implementation of `VectorSpace`. See #675. POC/Not for prod use.
-- [shapeless-spire](https://mvnrepository.com/artifact/org.typelevel/shapeless-spire)
diff --git a/build.sbt b/build.sbt
@@ -215,9 +215,7 @@ lazy val docs = project
       "VERSION" -> (if (isSnapshot.value)
                       previousStableVersion.value.getOrElse(version.value)
                     else
-                      version.value),
-      "COPYRIGHT_TO" -> java.time.LocalDate.now().getYear().toString(),
-      "AUTHORS" -> "Erik Osheim, Tom Switzer"
+                      version.value)
     ),
     // NOTE: disable link hygine to supress dead link warnings because mdoc does not go well with Jekyll
     mdocExtraArguments ++= Seq("--no-link-hygiene")
@@ -332,26 +330,26 @@ lazy val docSettings = Seq(
   micrositeDocumentationUrl := "https://www.javadoc.io/doc/org.typelevel/spire_2.13/latest/spire/index.html",
   micrositeDocumentationLabelDescription := "API Documentation",
   micrositeExtraMdFiles := Map(
+    file("AUTHORS.md") -> ExtraMdFileConfig(
+      "authors.md",
+      "home",
+      Map("title" -> "Authors", "section" -> "Home", "position" -> "5")
+    ),
     file("CHANGES.md") -> ExtraMdFileConfig(
       "changes.md",
       "home",
       Map("title" -> "Changes", "section" -> "Home", "position" -> "2")
     ),
-    // Note: CONTRIBUTING.md, CODE_OF_CONDUCT.md and COPYING is placed in pproject root directory so that github can detect it.
-    file("CONTRIBUTING.md") -> ExtraMdFileConfig("contributing.md",
-                                                 "home",
-                                                 Map("title" -> "Contributing", "section" -> "Home", "position" -> "3")
+    file("CONTRIBUTING.md") -> ExtraMdFileConfig(
+      "contributing.md",
+      "home",
+      Map("title" -> "Contributing", "section" -> "Home", "position" -> "3")
     ),
     file("DESIGN.md") -> ExtraMdFileConfig(
       "design.md",
       "home",
       Map("title" -> "Design notes", "section" -> "Home", "position" -> "4")
     ),
-    file("AUTHORS.md") -> ExtraMdFileConfig(
-      "authors.md",
-      "home",
-      Map("title" -> "Authors", "section" -> "Home", "position" -> "5")
-    ),
     file("FRIENDS.md") -> ExtraMdFileConfig(
       "friends.md",
       "home",

diff --git a/docs/src/main/mdoc/guide.md b/docs/src/main/mdoc/guide.md
@@ -123,14 +123,12 @@ behind Spire's generic math capabilities.
 #### Specialization
 
 To achieve speed on-par with direct (non-generic) code, you will need
-to use specialization. 
-
-About specialization, visit [scalac.io blog: Avoiding Unnecessary Object Instantiation with Specialized Generics](https://scalac.io/blog/specialized-generics-object-instantiation/)
-
-The good news is that most of Spire's code is
+to use [specialization](specialization). The good news is that most of Spire's code is
 already specialized (and tested for proper performance). The bad news
 is that you'll have to annotate all your generic code like so:
 
+[specialization]: https://www.scala-lang.org/old/sites/default/files/sids/dragos/Thu,%202010-05-06,%2017:56/sid-spec.pdf
+
 ```scala mdoc
 object Demo3 {
   import spire.algebra._
@@ -154,8 +152,7 @@ There are too many gotchas with specialization to list here. But the
  4. Specialization will increase bytecode size by a factor of x2-10.
 
 If you have questions about specialization feel free to ask on the
-mailing list or [gitter channel](https://gitter.im/typelevel/spire). You may notice that some code in Spire is structured in
-an unusual way, and often this is to make sure specialization works
+`#spire` channel on the [Typelevel Discord](https://discord.com/invite/XF3CXcMzqD). You may notice that some code in Spire is structured inan unusual way, and often this is to make sure specialization works
 properly.
 
 You may find that it's easy to develop generic code without using
@@ -189,13 +186,11 @@ properties themselves remain the same.
 
 #### Eq
 
-Spire provides an `Eq[A]` type class to represent type-safe
-equality.  This allows us to talk about types for which there isn't a
+Spire uses an `Eq[A]` type class to represent type-safe
+equality. This allows us to talk about types for which there isn't a
 computationally useful notion of equality, and also to avoid
 programming errors caused by universal equality.
 
-It means that comparing two values of incomparable types with `===` operator raises **compile error**, while Scala's standard `==` operator usually raises error at runtime.
-
 `Eq[A]` provides two operators
 
  * `eqv` (`a === b`) equality operator.
@@ -208,7 +203,6 @@ Spire requires that `eqv` obey the laws of an equivalence relation, namely:
  * if `a === b` then `a` is `b` (*anti-symmetry*)
  * if `a === b` and `b === c` then `a === c` (*transitivity*)
 
-
 The anti-symmetry property may seem confusing. The idea is that if `a === b`
 then `a` and `b` must be substitutable for each other, such that for any
 expression `f(x)`, `f(a) === f(b)`.

diff --git a/docs/src/main/mdoc/index.md b/docs/src/main/mdoc/index.md
@@ -24,28 +24,19 @@ code without having to "bake in" particular numeric representations. In most
 cases, generic implementations using Spire's specialized type classes perform
 identically to corresponding direct implementations.
 
-### Javadocs
-
-|library|link|
-|---|---|
-|spire| https://www.javadoc.io/doc/org.typelevel/spire_2.13/latest/spire/index.html |
-|spire-extras| https://www.javadoc.io/doc/org.typelevel/spire-extras_2.13/latest/spire/index.html |
-|spire-laws| https://www.javadoc.io/doc/org.typelevel/spire-laws_2.13/latest/spire/index.html |
-|spire-macros| https://www.javadoc.io/doc/org.typelevel/spire-macros_2.13/latest/spire/index.html |
-
+### Scaladoc
+[![Core](https://javadoc.io/badge2/org.typelevel/spire_2.13/javadoc.svg)](https://javadoc.io/doc/org.typelevel/spire_2.13)
+[![Extras](https://javadoc.io/badge2/org.typelevel/spire-extras_2.13/javadoc.svg)](https://javadoc.io/doc/org.typelevel/spire-extras_2.13)
+[![Laws](https://javadoc.io/badge2/org.typelevel/spire-laws_2.13/javadoc.svg)](https://javadoc.io/doc/org.typelevel/spire-laws_2.13)
+[![Macros](https://javadoc.io/badge2/org.typelevel/spire-macros_2.13/javadoc.svg)](https://javadoc.io/doc/org.typelevel/spire-macros_2.13)
 
 Spire is provided to you as free software under the
 [MIT license](https://github.com/typelevel/spire/blob/main/COPYING).
 
 ### Organization
 
-We spire (and typelevel) have [dicord](https://discord.com/invite/XF3CXcMzqD), [gitter chat](https://gitter.im/typelevel/spire) and [mailing list](https://groups.google.com/group/typelevel/).
-
-- [typelevel dicord](https://discord.com/invite/XF3CXcMzqD):  community for all typelevel-stack contributers and users.
-- [spire gitter](https://gitter.im/typelevel/spire) : place to go for announcements and discussions around Spire.
-- [mailng list](https://groups.google.com/group/typelevel/): place to go for announcements and discussions around [Typelevel projects](https://typelevel.org).
-
-
+There is `#spire` channel on the [Typelevel Discord](https://discord.com/invite/XF3CXcMzqD).
+It is the place to go for announcements and discussions around Spire.
 
 We also have a guide on [contributing to Spire](./extra_md/contributing.html) as well
 as a guide that provides information on [Spire's guide](./guide.html) and [design notes](./extra_md/design.html).
@@ -58,25 +49,20 @@ merging pull requests, and for helping to guide the direction of Spire:
  * Rüdiger Klaehn (*rklaehn@gmail.com*)
  * Denis Rosset (*physics@denisrosset.com*)
 
-#### Code of Conduct
+### Code of Conduct
 
-People are expected to follow the [Scala Code of Conduct](https://www.scala-lang.org/conduct/)
-when discussing Spire on the Github page, in Gitter, the IRC channel,
+People are expected to follow the [Typelevel Code of Conduct](https://typelevel.org/code-of-conduct.html)
+when discussing Spire on the Github page, in Discord, Gitter, the IRC channel,
 mailing list, and other official venues.
 
-Concerns or issues can be sent to any of Spire's maintainers, or to the
-[Typelevel](https://typelevel.org/about.html) organization.
+Concerns or issues can be sent to any of Spire's maintainers, or to any of the
+[designated CoC contacts](https://typelevel.org/code-of-conduct.html) for Typelevel.
 
 ### Set up
 
-Spire is currently available for Scala 2.11, 2.12 and 2.13, for the
+Spire is currently available for Scala 2.13 and 3.1+, for the
 JVM and JS platforms. 
 
-**Since v0.18.0, spire is available for Scala 3!**. 
-
-If you have already used spire of older version, check [migration guide](./extra_md/changes.html#version-0180-m1) because there are some breaking changes.
-
-
 To get started with SBT, simply add the following to your `build.sbt` file:
 
 ```
@@ -86,14 +72,8 @@ libraryDependencies += "org.typelevel" %% "spire" % "@VERSION@"
 (Previous to 0.14.0, Spire was published under *org.spire-math*
 instead of *org.typelevel*.)
 
-For Maven instructions, and to download the jars directly, visit the Central Maven repository.
-
-|Scala version| Maven Repo|
-|---|---|
-| 2.11.x|https://search.maven.org/artifact/org.typelevel/spire_2.11|
-| 2.12.x|https://search.maven.org/artifact/org.typelevel/spire_2.12|
-| 2.13.x|https://search.maven.org/artifact/org.typelevel/spire_2.13|
-| 3.x|https://search.maven.org/artifact/org.typelevel/spire_3|
+For information on all the available versions, visit the
+[Scaladex entry](https://index.scala-lang.org/typelevel/spire).
 
 Here is a list of all of Spire's modules:
 
@@ -108,12 +88,13 @@ and uses this project to interoperate with [Cats](https://github.com/typelevel/c
 
 ### Playing Around
 
-If you are new to Scala, or does not have Scala (or sbt) locally, try spire at [scastie](https://scastie.scala-lang.org/LVRAHaJAS7qoVbUyoDgKNA) on browser. 
+The quickest way to try spire is in the browser with [Scastie](https://scastie.scala-lang.org/LVRAHaJAS7qoVbUyoDgKNA). 
 
 <script src="https://scastie.scala-lang.org/LVRAHaJAS7qoVbUyoDgKNA.js"></script>
 
 #### With Ammonite Repl
-If you have [ammonite](https://ammonite.io/), enter `amm` in your terminal to launch ammonite REPL.
+
+If you have [ammonite](https://ammonite.io/), you can use an interactive REPL session.
 
 ```scala
 Welcome to the Ammonite Repl 2.x.x
@@ -125,13 +106,11 @@ Welcome to the Ammonite Repl 2.x.x
 res: Complex[Double] = Complex(real = 10.472508533940392, imag = -73.46062169567367)
 ```
 
+#### With an IDE
 
-#### with `*.worksheet.sc`
-You can also play around with IntelliJ or VS Code & Metals.
-
-For example, create `spire.worksheet.sc` and copy-paste the following code snippet.
+You can also play around with [IntelliJ](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html) or [VS Code and Metals](https://scalameta.org/metals/docs/editors/vscode/).
 
-Then, open `spire.worksheet.sc` with IntelliJ or CS Code (needs [metals VS Code extension](https://scalameta.org/metals/docs/editors/vscode/)).
+Create a [worksheet](https://scalameta.org/metals/docs/editors/vscode/#worksheets) file `spire.worksheet.sc` in your IDE and copy-paste the following code snippet.
 
 ```scala
 import $ivy.`org.typelevel::spire:@VERSION@`
@@ -141,7 +120,8 @@ import spire.implicits._
 Complex(3.0,5.0).sin
 res: Complex[Double] = Complex(real = 10.472508533940392, imag = -73.46062169567367)
 ```
-#### with git and sbt
+
+#### With git and sbt
 If you clone the Spire repo, you can get a taste of what Spire can do using
 SBT's console. Launch `sbt` and at the prompt, type `coreJVM/console`:
 
@@ -451,7 +431,7 @@ object SIDemo {
 }
 ```
 
-Spire also provides a loop macro called `cfor`(renamed to `fastFor` in v0.18.0) whose syntax bears a slight
+Spire also provides a loop macro called `fastFor` (previously known as `cfor`) whose syntax bears a slight
 resemblance to a traditional for-loop from C or Java. This macro expands to a
 tail-recursive function, which will inline literal function arguments.
 
@@ -622,7 +602,7 @@ measure relative as well as absolute performance.
 Code is offered as-is, with no implied warranty of any kind. Comments,
 criticisms, and/or praise are welcome, especially from numerical analysts! ;)
 
-Copyright 2011-@COPYRIGHT_TO@ @AUTHORS@
+Copyright 2011-2017 Erik Osheim, Tom Switzer
 
 A full list of contributors can be found in [AUTHORS.md](./extra_md/authors.html).