CodeEditApp/CodeEdit

✨ Help Documentation

jasonplatts opened this issue · 12 comments

jasonplatts commented

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 commented

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

  • 👍1
  • 🚀2
jasonplatts commented

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

jasonplatts commented

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 commented

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

I think it looks great

  • 👍1
lukepistrol commented

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

jasonplatts commented

That would be awesome @lukepistrol. Thanks!!

jasonplatts commented

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 commented

Will start gathering the resources tomorrow!

jasonplatts commented

Thank you! No rush.

lukepistrol commented

Some Resources:

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 commented

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

lukepistrol commented

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 😉

  • 😄2