✨ Help Documentation

[jasonplatts]

Overview

Help documentation will be needed for the CodeEdit application and Extension API. @austincondiff and I discussed using the DocC documentation compiler, which converts Markdown-based text into documentation for Swift projects. This is the same documentation framework used by Xcode.

DocC is being used for internal documentation. GitBook is being used for the extension API documentation and is WIP. Please see the Extension API Repository.

[lukepistrol]

DocC is great. Even deployable on GitHub Pages or any other web server! 👍🏻

[jasonplatts]

I have assigned myself to this issue to monitor and contribute as the project progresses, but anyone please feel free to contribute.

[jasonplatts]

DocC is great. Even deployable on GitHub Pages or any other web server! 👍🏻

Sounds good Luke! Awesome to discover that it integrates with Github!

[lukepistrol]

Just did it with a personal project of mine: https://lukepistrol.github.io/KrakenAPI/documentation/krakenapi/

I think it looks great

[lukepistrol]

I can post some resources on how to compile and some tricks I learned doing above mentioned docs.

[jasonplatts]

That would be awesome @lukepistrol. Thanks!!

[jasonplatts]

Just did it with a personal project of mine: https://lukepistrol.github.io/KrakenAPI/documentation/krakenapi/

I think it looks great

Love it! Looks great. Nice work!

[lukepistrol]

Will start gathering the resources tomorrow!

[jasonplatts]

Thank you! No rush.

[lukepistrol]

Some Resources:

• https://www.swift.org/documentation/docc/
• https://developer.apple.com/documentation/xcode/writing-symbol-documentation-in-your-source-files
• https://developer.apple.com/documentation/xcode/adding-structure-to-your-documentation-pages
• https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/publishing-to-github-pages/

Tips:

Static Hosting:

In root directory of project

swift package --allow-writing-to-directory [path-to-docs-directory] \
    generate-documentation --target [target-name] \
    --disable-indexing \
    --transform-for-static-hosting \
    --hosting-base-path [hosting-base-path] \
    --output-path [path-to-docs-directory]

• path-to-docs-directory – The path to the documentation catalog e.g. CodeEdit/Documentation.docc
• target-name – e.g. CodeEdit
• hosting-base-path – where the static page will be hosted. e.g. CodeEdit the page will (after setup in GitHub) be available at codeeditapp.github.io/CodeEdit/documentation/codeedit

This message will be edited with more resources in future!

[lukepistrol]

Something we could consider doing: Compiling the DocC catalog with a Github Workflow so it always stays up to date.