Merge branch 'develop'

Sources/DocCArchive/Schema_0_1/Content/Content.swift

@@ -3,13 +3,17 @@
 //  DocCArchive
 //
 //  Created by Helge Heß.
-//  Copyright © 2021 ZeeZide GmbH. All rights reserved.
+//  Copyright © 2021-2022 ZeeZide GmbH. All rights reserved.
 //
 
 extension DocCArchive.DocCSchema_0_1 {
 
   /**
    * Content in a ``Section`` or a ``Chapter``.
+   * E.g. headings, paragraphs and lists. Also "steps" for tutorials.
+   *
+   * Don't confuse this actual ``Content`` with a (`"kind": "content"`)
+   * ``Section/Kind-swift.enum/content(_:)``.
    */
   public enum Content: Equatable, CustomStringConvertible, Codable {
 
@@ -21,17 +25,89 @@ extension DocCArchive.DocCSchema_0_1 {
       case experiment
     }
 
+    /**
+     * An item within a ``unorderedList(_:)`` or ``orderedList(_:)``
+     * ``Content`` value.
+     * Just a list of more ``Content`` rendered as part of the item.
+     */
     public struct Item: Equatable, Codable {
       public var content : [ Content ]
     }
+
+    public enum TableHeaderKind: String, Codable, Equatable  {
+      /**
+       * Presumably there are more styles but `row`. `row` is the result of
+       * this Markdown:
+       * ```
+       * | Column 1 Title | Column 2 Title       |
+       * | -------------- | -------------------- |
+       * | `case 1`       | Case 1 description.  |
+       * | `case 2`       | Case 2 description.  |
+       * ```
+       */
+
+      /// This seems to say that the first row is the header row.
+      case row
+    }
+
+    /**
+     * A ``TableCell`` is an array of nested ``Content`` values,
+     * similar to ``Item``.
+     * It is kept as part of a ``TableRow``.
+     */
+    public typealias TableCell = [ Content ]
+
+    /**
+     * A ``TableRow`` is an array of ``TableCell``s,
+     * which themselves are just arrays of ``Content`` values.
+     */
+    public typealias TableRow = [ TableCell ]
 
+    /**
+     * A header, like an HTML H1/H2 tag.
+     * Must have an anchor ID, a level (1..6 presumably) and a plain text.
+     *
+     * Looks like this in JSON:
+     *
+     *     { "anchor": "overview",
+     *       "level": 2,
+     *       "type": "heading",
+     *       "text": "Overview" }
+     */
     case heading      (text: String, anchor: String, level: Int)
+
     case aside        (style: Style, content: [ Content ])
     case paragraph    (inlineContent: [ InlineContent ])
     case codeListing  (CodeListing)
+
+    /// A step of a tutorial
     case step         (Step)
+
     case orderedList  ([ Item ])
     case unorderedList([ Item ])
+
+    /**
+     * A table, usually written as Markdown.
+     *
+     * The headerKind supported so far is ``TableHeaderKind/row``,
+     * let us know if others exist.
+     *
+     * The table is represented by a set of ``TableRow``s,
+     * which is just an array of ``TableCell``s,
+     * which are just an array of nested ``Content`` values.
+     * 
+     * Example:
+     * ```
+     * | Column 1 Title | Column 2 Title       |
+     * | -------------- | -------------------- |
+     * | `case 1`       | Case 1 description.  |
+     * | `case 2`       | Case 2 description.  |
+     * ```
+     */
+    case table(headerKind: TableHeaderKind, rows: [ TableRow ])
+
+
+    // MARK: - Description
 
     public var description: String {
       switch self {
@@ -47,13 +123,17 @@ extension DocCArchive.DocCSchema_0_1 {
         case .paragraph    (let icontent) : return "<p>\(icontent)</p>"
         case .codeListing  (let code)     : return code.description
         case .step         (let step)     : return step.description
+        case .table(let header, let rows) :
+          return "<table header=\(header)>\(rows)</table>"
       }
     }
 
+
     // - MARK: Codable
 
     private enum CodingKeys: String, CodingKey {
       case content, anchor, level, type, text, style, inlineContent, items
+      case header, rows
     }
 
     public init(from decoder: Decoder) throws {
@@ -86,6 +166,11 @@ extension DocCArchive.DocCSchema_0_1 {
         case "step":
           let content = try Step(from: decoder)
           self = .step(content)
+        case "table":
+          let headerKind =
+            try container.decode(TableHeaderKind.self, forKey: .header)
+          let rows = try container.decode([ TableRow ].self, forKey: .rows)
+          self = .table(headerKind: headerKind, rows: rows)
         default:
           throw DocCArchiveLoadingError.unsupportedContentType(type)
       }
@@ -119,6 +204,10 @@ extension DocCArchive.DocCSchema_0_1 {
         case .step(let content):
           try container.encode("step"          , forKey: .type)
           try content.encode(to: encoder)
+        case .table(let headerKind, let rows):
+          try container.encode("table"         , forKey: .type)
+          try container.encode(headerKind      , forKey: .header)
+          try container.encode(rows            , forKey: .rows)
       }
     }
   }

Sources/DocCArchive/Schema_0_1/Sections/Section.swift

@@ -3,7 +3,7 @@
 //  DocCArchive
 //
 //  Created by Helge Heß.
-//  Copyright © 2021 ZeeZide GmbH. All rights reserved.
+//  Copyright © 2021-2022 ZeeZide GmbH. All rights reserved.
 //
 
 extension DocCArchive.DocCSchema_0_1 {
@@ -12,9 +12,22 @@ extension DocCArchive.DocCSchema_0_1 {
     case conformsTo
   }
 
+  /**
+   * A `Section` within for example the `primaryContentSections`.
+   *
+   * For example a `struct` documentation might begin with
+   * ``Kind-swift.enum/declarations(_:)``
+   * and then carry custom content in a
+   * ``Kind-swift.enum/content(_:)``
+   * section.
+   *
+   * Don't confuse the actual ``Content`` with a (`"kind": "content"`) section
+   * (which carries an array of ``Content`` values).
+   */
   public struct Section: Equatable, CustomStringConvertible, Codable {
 
     public enum Kind: Equatable, CustomStringConvertible {
+
       case generic
       case relationships(RelationshipType)
       case declarations ([ Declaration ])

Tests/DocCArchiveTests/DocumentDecodingTests.swift

@@ -3,7 +3,7 @@
 //  DocCArchiveTests
 //
 //  Created by Helge Heß.
-//  Copyright © 2021 ZeeZide GmbH. All rights reserved.
+//  Copyright © 2021-2022 ZeeZide GmbH. All rights reserved.
 //
 
 import XCTest
@@ -12,15 +12,48 @@ import XCTest
 final class DocumentDecodingTests: XCTestCase {
 
   static var allTests = [
-    ( "testSimpleTutorial"              , testSimpleTutorial              ),
-    ( "testIssue7Fail"                  , testIssue7Fail                  ),
-    ( "testIssue9FailAttributeFragment" , testIssue9FailAttributeFragment ),
+    ( "testSimpleTutorial"               , testSimpleTutorial               ),
+    ( "testIssue7Fail"                   , testIssue7Fail                   ),
+    ( "testIssue9FailAttributeFragment"  , testIssue9FailAttributeFragment  ),
     ( "testIssue10FailTypeMethodRoleHeading",
       testIssue10FailTypeMethodRoleHeading ),
-    ( "testIssue11FailUnorderedList"    , testIssue11FailUnorderedList    ),
-    ( "testAllDataJSONInSlothCreator"   , testAllDataJSONInSlothCreator   ),
-    ( "testIssue12FailAsideWarningStyle", testIssue12FailAsideWarningStyle )
+    ( "testIssue11FailUnorderedList"     , testIssue11FailUnorderedList     ),
+    ( "testAllDataJSONInSlothCreator"    , testAllDataJSONInSlothCreator    ),
+    ( "testIssue12FailAsideWarningStyle" , testIssue12FailAsideWarningStyle ),
+    ( "testTableIssue6"                  , testTableIssue6 )
   ]
+
+  func testTableIssue6() throws {
+    let url  = Fixtures.baseURL.appendingPathComponent("TableIssue6.json")
+    let data = try Data(contentsOf: url)
+
+    let document : DocCArchive.Document
+
+    print("Decoding:", url.path)
+    do {
+      document = try JSONDecoder().decode(DocCArchive.Document.self, from: data)
+
+      let section = try XCTUnwrap(
+        document.primaryContentSections?.dropFirst().first,
+        "did not find section with table"
+      )
+
+      guard case .content(let contents) = section.kind else {
+        XCTFail("did not find content section"); return
+      }
+      guard case .table(let header, let rows) = contents.dropFirst().first else {
+        XCTFail("did not find table"); return
+      }
+      XCTAssertEqual(header, .row, "expected to find row-type header")
+      XCTAssert(rows.count == 3) // 1 header row, 2 content rows
+    }
+    catch {
+      print("ERROR:", error)
+      XCTFail("failed to decode: \(error)")
+      return
+    }
+    XCTAssertEqual(document.schemaVersion, .init(major: 0, minor: 1, patch: 0))
+  }
 
   func testIssue12FailAsideWarningStyle() throws {
     let url  = Fixtures.baseURL.appendingPathComponent("Issue12Fail.json")

Tests/DocCArchiveTests/Fixtures.swift

@@ -3,7 +3,7 @@
 //  DocCArchiveTests
 //
 //  Created by Helge Heß.
-//  Copyright © 2021 ZeeZide GmbH. All rights reserved.
+//  Copyright © 2021-2022 ZeeZide GmbH. All rights reserved.
 //
 
 import Foundation
@@ -13,14 +13,15 @@ enum Fixtures {
   static let baseURL = URL(fileURLWithPath: #filePath)
                          .deletingLastPathComponent()
                          .appendingPathComponent("Fixtures/", isDirectory: true)
-
+
+  /// Where docc archives for bigger tests are being stored, currently
+  /// in `~/Downloads`.
+  static let testArchivesDir = FileManager.default.homeDirectoryForCurrentUser
+                                 .appendingPathComponent("Downloads")
+
   static let slothCreatorArchive =
-    FileManager.default.homeDirectoryForCurrentUser
-      .appendingPathComponent("Downloads")
-      .appendingPathComponent("SlothCreator.doccarchive")
+    testArchivesDir.appendingPathComponent("SlothCreator.doccarchive")
 
   static let issue7Archive =
-    FileManager.default.homeDirectoryForCurrentUser
-      .appendingPathComponent("Downloads")
-      .appendingPathComponent("LLabsWishlist.doccarchive")
+    testArchivesDir.appendingPathComponent("LLabsWishlist.doccarchive")
 }