Any way to merge the index.json for multiple framework hosting on single Static site ?

[dreampiggy]

May related to https://github.com/apple/swift-docc/issues/328

Issue

Currently seems the index.json is used for left search filed searching the symbols.

However, the swift-docc-render/src/utils/data.js here seems only support query single one index.json in the whole site.

So, for Static site hosting, does this means I need to merge all the other frameworks into the final big index json files ? Is there any tools to do this ?

Alternate way

Currently in my example, I change this into index/${framework_name}/index.json and hosting multiple frameworks documentation.

- documentation/
  foo/index.html
  bar/index.html
- data/
  foo/foo.json
  bar/bar.json
- index/
  foo/index.json
  bar/index.json

[mportiz08]

You're right that the index.json is currently hardcoded to fetch the navigator data for a single framework. Ideally, I think there should be multiple "index" JSON files that map to each individual framework/module so that this kind of hosting setup is achievable (similar to your described workaround).

It might also be possible to merge the index data for every framework/module into a single file, however I believe the specification of that file was designed in a way to map to a single one, so I think the right thing to do would be to update both DocC and DocC-Render in a coordinated way to support multiple index files in a built single archive.

[mportiz08]

I think the implementation of this will likely be heavily impacted by https://github.com/apple/swift-docc/issues/317

[franklinsch]

Ideally, I think there should be multiple "index" JSON files that map to each individual framework/module so that this kind of hosting setup is achievable (similar to your described workaround).

I think this would work well. Could we build this in a backwards-compatible way, where DocC Render first tries to find the framework-specific index.json and falls back to a global one?

[adam-rocska]

@franklinsch I just hacked around locally and to me it honestly seems like it can be covered in a backwards-compatible way.

Note, I'm not a project member / official contributor / whatever, but so far it seems like I could merry multiple library products in one doc'. But had to go pretty deep, like for example:

{
  "kind": "symbol",
  "metadata": {
    "externalID": "Beton",
    "symbolKind": "module",
    "role": "collection",
    "title": "Beton",
    "roleHeading": "Framework",
    "modules": [
      {
        "name": "Beton"
+      },
+      {
+        "name": "XCTBeton"
+      },
    ]
  },
///  ...

btw, I just learned this cool "diff" feature from @vknabel

Right path?

I'm not sure though if this route I took was the right path, since practically in our case, though both Beton and XCTBeton are intentionally in the same Swift Package, they aren't practically different modules of the same Framework, but instead two libraries.

One enhances Foundation and the other XCTest. These boxes shouldn't touch. they're in the same Package & repo because they would otherwise cross-depend in a weird way.

Is help needed?

I'm personally all up to put in some meat into this issue if someone, anyone could be my tourguide for an hour to teach me the ins and outs of this renderer and how things end up here from docc. I mean, for real. With an initial swing I'm willing to take responsibility for this issue. My company needs it ¯\(ツ)/¯

[d-ronnqvist]

Merging the index is part of the plan for combined documentation for multiple targets in DocC.

@franklinsch Should we move this issue to the swift-docc repository instead?

[franklinsch]

Yes that makes sense. Is there a way by which @adam-rocska can help with some of the work?

[dobromir-hristov]

When we developed this feature with Ethan, afaik the index.json was meant to hold multiple technologies in case we support those in the future, as @d-ronnqvist said.

As far as docc-render is concerned, there should be no extra work to do. If you navigate from FooKit to BarKit it should just try to find those in the JSON, for the language you are on.

[TosinAF]

@adam-rocska also happy to help if possible.