Not understanding docc links

Development Swift-DocC
1

Given the following Swift Command line tool example folder hierarchy, I'd like to know how to link to README.md from MyCommandLineTool.md

MyPackage
  |-- README.md
  |-- Package.swift
  |-- Sources
      |-- MyCommandLineTool
          |-- main.swift
          |-- MyCommandLineTool.docc
              |-- MyCommandLineTool.md
2

Hey Neil,

If you're code is hosted somewhere (such as GitHub, GitLab, etc), you can make an external HTML link. You probably already know the pattern, but just in case it looks something like:

[link to README](https://hosting-service/neil456/project/blob/main/README.md)

The content of the README.md file isn't included in the documentation collected and assembled by DocC, so it's otherwise not available.

You could copy it into the .docc folder, but there's tradeoffs with that which can be frustrating as well - extra scripting, different rendering supported within DocC than from something like being hosted on GitHub, etc.

When I want to leverage something like this, I reach for an external link.

3

Thanks for the quick response.

This is proprietary code and is not available on the web.

To make sure I understand, you are saying that a docc article cannot link to any other articles outside of the .docc catalog folder in a package?

That seems unnecessarily restrictive as I like to keep my documentation close to my code and I don't want to duplicate the top level readme in the docc source.

4

Yes, that's correct. The source for all non-symbol content that gets compiled into a Documentation archive is the DocC catalog. DocC takes the symbols from the actual executables and/or library code and mixes it in with what's in the catalog to assemble the DocC Archive. Also note that what it assembles isn't just "flat" HTML pages, but a single-page Javascript application that reads data from the archive to present the content.

I certainly understand your frustration. Dependency on how your readers consume your documentation, You might find it worthwhile to copy the README into the documentation catalog just prior to generating the documentation, at which point you can reference it (assuming it follows a general "Article" format) within DocC. For most of the README's I've seen (public ones, obviously I don't know your setup), it may be different to use effectively in this format - but it might solve the issue of "getting it to your readers" while keeping it a top-level file in a traditionally-expected location.

5

Thanks. This was my first attempt at docc and i'm learning it does not seem to be for me. I have LaTeX tools that were developed years ago that allow me to keep documentation and code together to produce HTML or PDF. I guess I continue using them for non-API docs.