Add Flag to Include Resources

[drekka]

Currently I've been adding a bash cp command after generating the documentation with Jazzy in order to copy additional resources into the documentation. In my case the cp copies images stored in a directory into the generated docs. This works ok for then publishing the docs as html, but the images are not included into the docset Jazzy creates in docs/docset.

I think I'd like to see a new argument to Jazzy. Something like this:

jazzy --include-files file mask, ...

So I could do this:

jazzy --include-files images/*.png,images/*.jpg

As a further justification, whilst images can be referenced via links to resources stored on the internet, it won't work when the docs are being passed around on some internal company networks (with heavy security) or when the computer is offline.

[SDGGiesbrecht]

Thank you, @drekka.

[johnfairh]

So we want to:

• get a list of resource files from user
• give resources slugged / url-safe / unique names
• include those files in site + docset, let's say into a 'Resources' subdir
• make it easy to reference resources from link and inline-image markdown -- I think it works to just let these just use the original resource filename and have jazzy convert that to the relative mapped slugged URL.

So given:

jazzy --resources 'My Awesome.png'

and some markdown in eg. a class doc comment:

[This text links to the image](My Awesome.png)
![Image's alt text](My Awesome.png)

we get html:

<a href="../Resources/my-awesome.png">This text links to the image</a>
<img src="../Resources/my-awesome.png" alt="Image's alt text">

As a follow-on would make sense to do the same thing for documentation markdown files as requested by a couple of other issues.

[SDGGiesbrecht]

@johnfairh, That would work well for the .md files.

But for documentation comments, Xcode’s Quick Help will not have those resources and I can see that being a source for confusion.

I think for documentation comments I would propose maybe one of the following:

A) Make a configuration option available to specify the base URL of the canonical location the documents will be hosted. Then documentation comments should point to absolute URLs in that canonical location for Xcode’s sake. Jazzy would recognize the matching prefix and strip it, so Jazzy’s version points at its own local copies because it can guarantee their existence. Users who will not be hosting anything online can use a mock canonical URL (e.g. does‐not‐exist.com/docs) and Jazzy will still strip it and point to local resources. Since the user has to choose a canonical URL (real or fake), it should be more obvious to him that fake URLs will not work with other tools.

B) Jazzy treats them as you said, but whenever it encounters a link to a local resource in a documentation comment, it throws a warning in much the same way it does when it encounters something undocumented. That way users are clearly notified that their documentation only works with Jazzy—not Xcode or other tools. It would be reasonable to disable all such warnings with a configuration option.

Option B is simpler, but would make it impossible for a project to support both Jazzy’s local resources and Xcode at once, forcing users to choose between the two.

[johnfairh]

Good point. Could do (A) by default, spot absolute links (with any prefix) to resource files + rewrite them as relative. Then still support the option to 'rewrite only these urls' as you describe to deal with unwanted/specific rewriting.