Merge pull request #2160 from typelevel/fix_docs

Fix docs and check makeSite passes in CI

Author: jatcwang

.github/workflows/ci.yml

@@ -81,8 +81,8 @@ jobs:
       - name: Check there are no uncommitted changes in git (to catch generated files that weren't committed)
         run: sbt '++ ${{ matrix.scala }}' checkGitNoUncommittedChanges
 
-      - name: Check Doc Site (2.13.15 only)
-        if: matrix.scala == '2.13.15'
+      - name: Check Doc Site (2.13 only)
+        if: matrix.scala == '2.13'
         run: sbt '++ ${{ matrix.scala }}' docs/makeSite
 
       - name: Make target directories

build.sbt

@@ -68,8 +68,8 @@ ThisBuild / githubWorkflowBuildPostamble ++= Seq(
   ),
   WorkflowStep.Sbt(
     commands = List("docs/makeSite"),
-    name = Some(s"Check Doc Site ($scala213Version only)"),
-    cond = Some(s"matrix.scala == '$scala213Version'")
+    name = Some(s"Check Doc Site (2.13 only)"),
+    cond = Some(s"matrix.scala == '2.13'")
   )
 )
 
@@ -539,6 +539,7 @@ lazy val docs = project
       "scalaVersion" -> scalaVersion.value
     ),
     mdocIn := baseDirectory.value / "src" / "main" / "mdoc",
+    mdocExtraArguments ++= Seq("--no-link-hygiene"),
     Compile / paradox / sourceDirectory := mdocOut.value,
     makeSite := makeSite.dependsOn(mdoc.toTask("")).value
   )

modules/docs/src/main/mdoc/docs/15-Extensions-PostgreSQL.md

@@ -116,7 +116,7 @@ object MyEnum extends Enumeration {
   val foo, bar = Value
 }
 
-implicit val MyEnumMeta = pgEnum(MyEnum, "myenum")
+implicit val MyEnumMeta: Meta[MyEnum.Value] = pgEnum(MyEnum, "myenum")
 ```
 
 ```scala mdoc
@@ -214,14 +214,14 @@ In addition to the general types above, **doobie** provides mappings for the fol
 
 [Geographic types](http://postgis.net/workshops/postgis-intro/geography.html) mappings are defined in a different object (`pgisgeographyimplicits`), to allow geometric types using geodetic coordinates.
 
-```
+```scala
 import doobie.postgres.pgisgeographyimplicits._
 
 // or define the implicit conversion manually
 
-implicit val geographyPoint: Meta[Point] =
-  doobie.postgres.pgisgeographyimplicits.PointType
+implicit val geographyPoint: Meta[Point] = doobie.postgres.pgisgeographyimplicits.PointType
 ```
+
 - Point
 - Polygon
 - MultiPoint
@@ -242,17 +242,17 @@ The following range types are supported, and map to **doobie** generic `Range[T]
 - the `tstzrange` schema type maps to `Range[java.time.OffsetDateTime]`
 
 Non empty range maps to:
-```scala mdoc:silent
+```scala
 case class NonEmptyRange[T](lowerBound: Option[T], upperBound: Option[T], edge: Edge) extends Range[T]
 ```
 
 Empty range maps to:
-```scala mdoc:silent
+```scala
 case object EmptyRange extends Range[Nothing]
 ```
 To control the inclusive and exclusive bounds according to the [PostgreSQL](https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-INCLUSIVITY) specification you need to use a special `Edge` enumeration when creating a `Range`:
 
-```scala mdoc:silent
+```scala
 object Edge {
   case object ExclExcl extends Edge
   case object ExclIncl extends Edge
@@ -271,13 +271,14 @@ import doobie.postgres.rangeimplicits._
 
 To create for example custom implementation of `Range[Byte]` you can use the public method which declared in the following package `doobie.postgres.rangeimplicits`:
 
-```scala mdoc:silent
+```scala
 def rangeMeta[T](sqlRangeType: String)(encode: T => String, decode: String => T): Meta[Range[T]]
 ```
 
 For a `Range[Byte]`, the meta and bounds encoder and decoder would appear as follows:
 ```scala mdoc:silent
 import doobie.postgres.rangeimplicits._
+import doobie.postgres.types.Range
 
 implicit val byteRangeMeta: Meta[Range[Byte]] = rangeMeta[Byte]("int4range")(_.toString, _.toByte)
 

modules/docs/src/main/mdoc/docs/17-FAQ.md

@@ -150,7 +150,7 @@ As of **doobie** 0.4 there is a reasonable solution to the logging/instrumentati
 There are a lot of ways to handle `SQLXML` so there is no pre-defined strategy, but here is one that maps `scala.xml.Elem` to `SQLXML` via streaming.
 
 ```scala mdoc:silent
-import doobie.enum.JdbcType.Other
+import doobie.enumerated.JdbcType.Other
 import java.sql.SQLXML
 import scala.xml.{ XML, Elem }
 
@@ -181,7 +181,7 @@ Domains with check constraints will type check as DISTINCT. For Doobie later tha
 ```scala mdoc:silent
 import cats.data.NonEmptyList
 import doobie._
-import doobie.enum.JdbcType
+import doobie.enumerated.JdbcType
 
 object distinct {