Using DocC to create documentation for standalone markdown files

Development Swift-DocC
1

Hi! My apologies in advance if this is indeed documented somewhere, but I had to struggle a bit to find out how to get docc to render standalone markdown content. Maybe this'll be helpful for other folks like me in the future, and also by posting it here someone can correct me if I'm missing something obvious.

  1. Create an empty folder with a prefix .docc.

    mkdir Documentation.docc

  2. Add the following minimal Markdown.

    # Hello

@Metadata {
    @TechnologyRoot
}

World

  3. Preview using docc.

    pbpaste > Documentation.docc/Hello.md
xcrun docc preview Documentation.docc

I also wrote down notes from my first impressions with DocC - these might be useful to the DocC team members to see how the DocC documentation looks for newcomers. There's a bit of jesting in the post, but it's only for humor - I fully realize that rendering standalone markdown is not the primary use case for docc, so it is understandable that the workflow for this is not fully documented.

I also found a (rather harmless) crash when DocC tries to parse an Info.plist without a bundle id - more info about that is also in the post.

The rendered documentation indeed does look beautiful, so thank you all for your work on docc.

2 Likes
2

Hi @mnvr, glad to hear you were able to get things working.

As far as making things easier, you might find this post by @sofiaromorales interesting, which pitches an idea for making a new DocC command that makes it simple to get started with template content.

2 Likes
3

Hi @mnvr! I'm implementing an 'init' command in DocC, and the template is very similar to the one you posted. I'm hoping it will make the experience easier :smile:

3 Likes
4

Yes, a docc init will be nice indeed!

Thank you both for continuously improving the docc experience :blush:

2 Likes
5

I am going to be cheeky but I have love and respect for all you OSS devs working on projects like these.
Unfortunately documentation seems to be lacking. Here's the journey I just took:

Eagerly, after pouring hours into docc + swift-doc-plugin trying to get both Tutorials and documentation generated from multiple targets hosted onto github (have yet to see someone achieve this), I stumble upon what I think is going to redeem hopeless venture:

❯ docc init
zsh: command not found: docc

...hmm [reads swift-docc docs]

Swift-DocC is also included in the Swift toolchain for both macOS and Linux.

To see instructions on how to use DocC from the CLI run

docc --help

I'm on a mac so I try again:

docc --help
zsh: command not found: docc

[Goes to Swift docc repo & CMD + F "install"]

0/0 results

Okay so then maybe??

xcrun docc init
Error: Unexpected argument 'init'
Usage: docc <subcommand>
  See 'docc --help' for more information.

.......

Maybe I have the wrong version? [Goes back to swift-docc repo and attempts to find the release where docc init was added.]

There's a single release...

[Runs CMD + F "init" on the release page] 0/0 results

LOL I have no idea what's going on but it seems like I am hallucinating or something.

Is there a complete guide anywhere on how to use this? Also why isn't docc init tagged in a release?

6

Hi Taylor - docc init isn't included in the Swift 5.10 toolchain. So when you try xcrun docc init, you'll run into an error.

If you want to use it you can install the trunk development Swift toolchain from Swift.org - Download Swift and invoke it using that version of Swift.

1 Like