CodeEdit icon indicating copy to clipboard operation
CodeEdit copied to clipboard

Published 20 hours ago • verified publisher icon CodeEditApp

✨ Help Documentation

Open jasonplatts opened this issue 3 years ago • 12 comments

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.

jasonplatts avatar Mar 19 '22 21:03 jasonplatts

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

lukepistrol avatar Mar 19 '22 21:03 lukepistrol

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

jasonplatts avatar Mar 19 '22 21:03 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!

jasonplatts avatar Mar 19 '22 21:03 jasonplatts

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

I think it looks great

lukepistrol avatar Mar 19 '22 21:03 lukepistrol

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

lukepistrol avatar Mar 19 '22 21:03 lukepistrol

That would be awesome @lukepistrol. Thanks!!

jasonplatts avatar Mar 19 '22 22:03 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!

jasonplatts avatar Mar 19 '22 22:03 jasonplatts

Will start gathering the resources tomorrow!

lukepistrol avatar Mar 20 '22 01:03 lukepistrol

Thank you! No rush.

jasonplatts avatar Mar 20 '22 01:03 jasonplatts

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 avatar Mar 20 '22 11:03 lukepistrol

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

lukepistrol avatar Mar 20 '22 16:03 lukepistrol

Something to note: Each module in CodeEditModules requires its own DocC catalog. Also it is not possible to link between modules or the main app.

Let's see what WWDC22 brings 😉

lukepistrol avatar Apr 04 '22 15:04 lukepistrol